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..88c1a908b74 100644 --- a/.openpublishing.redirection.json +++ b/.openpublishing.redirection.json @@ -1,39 +1,6600 @@ { "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/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 +6603,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 +6640,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 +6759,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 +6780,416 @@ }, { "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#caching", + "redirect_document_id": true + }, + { + "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#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" + }, + { + "source_path": "docs/organizations/settings/work/import-process/differences.md", + "redirect_url": "/previous-versions/azure/devops/organizations/settings/work/import-process/customize-process#differences" + }, + { + "source_path": "docs/organizations/settings/work/upgrade-support-hosted-to-inherited.md", + "redirect_url": "/azure/devops/organizations/work/change-process-from-hosted-to-inherited#supported-operations-for-moving-from-hosted-xml-to-an-inherited-process" + }, + { + "source_path": "docs/report/extend-analytics/example-analytics-widget.md", + "redirect_url": "/azure/devops/extend/develop/add-dashboard-widget" + }, + { + "source_path": "docs/extend/develop/add-chart.md", + "redirect_url": "/azure/devops/extend/develop/add-dashboard-widget" + }, + { + "source_path": "docs/integrate/concepts/service-hooks.md", + "redirect_url": "/azure/devops/service-hooks/overview" + }, + { + "source_path": "docs/organizations/accounts/manage-personal-access-tokens-via-api.md", + "redirect_url": "/azure/devops/organizations/accounts/use-personal-access-tokens-to-authenticate#pat-lifecycle-management-apis" + }, + { + "source_path": "docs/organizations/accounts/get-list-of-organizations-connected-to-azure-active-directory.md", + "redirect_url": "/azure/devops/organizations/accounts/get-list-of-organizations-connected-to-microsoft-entra-id" + }, + { + "source_path": "docs/boards/backlogs/set-up-your-backlog.md", + "redirect_url": "/azure/devops/boards/backlogs/create-your-backlog" } ] } - 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..56b8e06e6d7 100644 --- a/docs/artifacts/.openpublishing.redirection.artifacts.json +++ b/docs/artifacts/.openpublishing.redirection.artifacts.json @@ -9,6 +9,21 @@ "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 + }, + { + "source_path_from_root": "/docs/artifacts/maven/pom-and-settings.md", + "redirect_url": "/azure/devops/artifacts/maven/project-setup-maven", + "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..ac8843e896c 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,16 @@ 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. + +## Increase Artifacts storage limit + +[!INCLUDE [](includes/increase-storage-limit.md)] ## Related articles diff --git a/docs/artifacts/artifacts-key-concepts.md b/docs/artifacts/artifacts-key-concepts.md index ba8375bff82..e3a0a1a6f01 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 -monikerRange: '<= azure-devops' +ms.date: 02/12/2025 +monikerRange: '>= azure-devops-2020' "recommendations": "true" --- -# Key concepts for Azure Artifacts +# Azure Artifacts key concepts -[!INCLUDE [version-lt-eq-azure-devops](../includes/version-lt-eq-azure-devops.md)] +[!INCLUDE [version-gt-eq-2020](../includes/version-gt-eq-2020.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..845afd73cf0 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 -monikerRange: '<= azure-devops' +ms.date: 03/11/2025 +ms.custom: engagement-fy23 +monikerRange: '>= azure-devops-2020' "recommendations": "true" --- -# Azure Artifacts: best practices +# Azure Artifacts best practices -[!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] +[!INCLUDE [version-gt-eq-2020](../../includes/version-gt-eq-2020.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..2e788688ddf 100644 --- a/docs/artifacts/concepts/feeds.md +++ b/docs/artifacts/concepts/feeds.md @@ -1,115 +1,141 @@ --- -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.custom: peer-review-program ms.service: azure-devops-artifacts ms.topic: conceptual -ms.date: 04/07/2022 -monikerRange: '<= azure-devops' +ms.date: 06/03/2024 +monikerRange: '>= azure-devops-2020' --- -# What are feeds? +# What are Azure Artifacts feeds? -[!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] +[!INCLUDE [version-gt-eq-2020](../../includes/version-gt-eq-2020.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..4d02a30922b 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 +monikerRange: '>= azure-devops-2020' +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)] +[!INCLUDE [version-gt-eq-2020](../../includes/version-gt-eq-2020.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..17243ccb541 100644 --- a/docs/artifacts/concepts/symbols.md +++ b/docs/artifacts/concepts/symbols.md @@ -2,17 +2,16 @@ 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 -monikerRange: '<= azure-devops' +monikerRange: '>= azure-devops-2020' "recommendations": "true" --- # Symbols overview -[!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] +[!INCLUDE [version-gt-eq-2020](../../includes/version-gt-eq-2020.md)] To debug compiled executables from native languages like C and C++, you need symbol files that contain mapping information to the source code. These files are created from source code during compilation and generally have the PDB (program database) extension. Azure Artifacts offers a dedicated symbols server to publish your symbols. diff --git a/docs/artifacts/concepts/upstream-behavior.md b/docs/artifacts/concepts/upstream-behavior.md index f08a0c1dae1..978fa290ad3 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)] +[!INCLUDE [version-gt-eq-2020](../../includes/version-gt-eq-2020.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..f8d91a24aff 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 -monikerRange: '<= azure-devops' +ms.topic: overview +ms.date: 03/05/2025 +monikerRange: '>= azure-devops-2020' "recommendations": "true" --- -# Upstream sources +# What are upstream sources? -[!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] +[!INCLUDE [version-gt-eq-2020](../../includes/version-gt-eq-2020.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..e75e5ca57ce 100644 --- a/docs/artifacts/concepts/views.md +++ b/docs/artifacts/concepts/views.md @@ -5,31 +5,34 @@ ms.assetid: 28527A09-8025-4615-A746-9D213CF8202C ms.service: azure-devops-artifacts ms.topic: conceptual ms.date: 04/07/2022 -monikerRange: '<= azure-devops' +monikerRange: '>= azure-devops-2020' "recommendations": "true" --- # What are feed views? -[!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] +[!INCLUDE [version-gt-eq-2020](../../includes/version-gt-eq-2020.md)] Feed views enable developers to share a subset of package-versions with their consumers. A common use of feed views is to share package versions that have been tested and validated but hold back on packages that are still under development and/or didn't meet a certain quality bar. ## 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..6797f734bdf 100644 --- a/docs/artifacts/feeds/feed-permissions.md +++ b/docs/artifacts/feeds/feed-permissions.md @@ -4,14 +4,14 @@ 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 -monikerRange: '<= azure-devops' +ms.date: 03/15/2024 +monikerRange: '>= azure-devops-2020' "recommendations": "true" --- # Manage permissions -[!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] +[!INCLUDE [version-gt-eq-2020](../../includes/version-gt-eq-2020.md)] Azure Artifacts enables you to publish, consume, and store various types of packages in your feed. By configuring permissions for your feed, you can manage access to your packages and control who can interact with them. @@ -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..d1d5db74bdf 100644 --- a/docs/artifacts/feeds/project-scoped-feeds.md +++ b/docs/artifacts/feeds/project-scoped-feeds.md @@ -1,109 +1,91 @@ --- -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 -monikerRange: '<= azure-devops' +ms.date: 10/24/2024 +monikerRange: '>= azure-devops-2020' "recommendations": "true" --- -# Project-scoped feeds +# Feed scopes: Project vs organization feeds -[!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] +[!INCLUDE [version-gt-eq-2020](../../includes/version-gt-eq-2020.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**: +| **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, both the **Project Collection Build Service** and the project's **Build Service** of the project running the pipeline must be granted the appropriate role. | Only the **Project Collection Build Service** needs to be granted the appropriate role. | - * Project-scoped feeds inherit the visibility of the project. - * Organization-scoped feeds are always private by default. +> [!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**. -1. **Links**: +> [!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 a project-scoped feed includes the project. - * Example: `https://pkgs.dev.azure.com///_packaging//nuget/v3/index.json` +## Q&A - * The URL of an organization-scoped feed doesn't include a project. - * Example: `https://pkgs.dev.azure.com//_packaging//nuget/v3/index.json` +#### Q: How can I share packages with all users in my organization? -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. +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**. -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. +> [!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. -## Security policies +#### Q: How can I access a project-scoped feed in another project from my pipeline? -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). +To allow a pipeline to access a project-scoped feed in a different project, you need to grant access both at the project level (where the feed is hosted) and the feed level. -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. +- **Project permissions**: Navigate to the project hosting the feed, select **Project settings** > **Permissions** and then add your pipeline's *project build service* to the **Readers** group. -> [!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. +- **Feed permissions**: Navigate to the feed you want to access, select **Settings** > **Feed permissions**, and then add your *project build service* with one of the following roles: + - **Feed and Upstream Reader (Collaborator)**: If you want to view or download packages from the feed, or save packages from upstream sources. + - **Feed Publisher (Contributor)**: If you want to publish, promote, or deprecate packages, in addition to viewing or downloading packages from the feed, or save packages from upstream sources. -## Q&A +The *Project build service* identity is formatted as: `[Project name] Build Service ([Organization name])`. 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..bacf763a6ec 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 -monikerRange: '<= azure-devops' +ms.topic: how-to +ms.date: 02/19/2025 +monikerRange: '>= azure-devops-2020' --- -# 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)] +[!INCLUDE [version-gt-eq-2020](../../includes/version-gt-eq-2020.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..8878acd748f --- /dev/null +++ b/docs/artifacts/get-started-artifacts-ai.md @@ -0,0 +1,210 @@ +--- +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.update-cycle: 180-days +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..b392fb68079 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 -monikerRange: '<= azure-devops' +ms.date: 07/01/2024 +monikerRange: '>= azure-devops-2020' --- -# 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)] +[!INCLUDE [version-gt-eq-2020](../includes/version-gt-eq-2020.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..2e2339d7972 100644 --- a/docs/artifacts/get-started-npm.md +++ b/docs/artifacts/get-started-npm.md @@ -1,181 +1,124 @@ --- -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 with Azure Artifacts +description: Learn how to configure your npm project to publish and consume packages using 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 -monikerRange: '<= azure-devops' +ms.date: 06/17/2025 +monikerRange: '>= azure-devops-2020' "recommendations": "true" --- -# Get started with npm packages in Azure Artifacts +# Publish and download npm packages with Azure Artifacts -[!INCLUDE [version-lt-eq-azure-devops](../includes/version-lt-eq-azure-devops.md)] +[!INCLUDE [version-gt-eq-2020](../includes/version-gt-eq-2020.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. +With Azure Artifacts, you can publish and download npm packages from both your own feeds and public registries such as npmjs.com. This quickstart guides you through creating a feed, configuring your project, and managing npm packages using Azure Artifacts. -::: moniker range="tfs-2018" +## Prerequisites -## License the Azure Artifacts extension +| **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 Node.js and npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm). | -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). - -### Assign licenses in Team Foundation Server +## Create a feed -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**. +[!INCLUDE [](includes/create-feed.md)] -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. +## Connect to a feed -> [!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. +Azure Artifacts recommends using two separate configuration files. The first should be kept locally in the *$HOME* directory (Linux/macOS) or *$env.HOME* (Windows) to securely store your credentials. This allows the npm client to access your credentials for authentication. -1. From any collection in Team Foundation Server, hover over the settings menu and select **Users**. Then select **Package Management**. +In this section, you'll configure the second *npmrc* file, which should be placed in the same directory as your *package.json* file. - :::image type="content" source="media/users-hub-tfs.png" alt-text="Screenshot showing the user page in TFS"::: +This setup lets you share your configuration file without exposing your credentials. -1. Select **Assign**, enter the users you want to assign licenses, and then select **OK**. +::: moniker range="azure-devops" - * 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). +1. Sign in to your Azure DevOps organization, and then navigate to your project. - * 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. +1. Select **Artifacts**, select your feed from the dropdown menu, and then select **Connect to feed**. -::: moniker-end +1. In the left navigation pane, select **npm**. If this is your first time using Azure Artifacts with npm, make sure you've installed the prerequisites. -## Create a feed +1. Under the **Project setup** section, select **Windows** or **Other** depending on your operating system, then follow the provided instructions to configure your config file and connect to your Azure Artifacts 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. + :::image type="content" source="media/npm-project-setup-azure-devops.png" alt-text="A screenshot displaying how to set up an npm project and connect to a feed in Azure DevOps Services."::: -[!INCLUDE [](includes/create-feed.md)] +::: moniker-end -::: moniker range="azure-devops" -## Set up your .npmrc files +::: moniker range="azure-devops-2022" > [!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. +> The `vsts-npm-auth` is not supported in Azure DevOps Server. -1. Select **Artifacts**, and then select **Connect to feed**. +1. Sign in to your Azure DevOps collection, and then navigate to your project. - :::image type="content" source="media/connect-to-feed-azure-devops-newnav.png" alt-text="Screenshot showing how to connect to a feed"::: +1. Select **Artifacts**, select your feed from the dropdown menu, and then select **Connect to 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. In the left navigation pane, select **npm**. If this is your first time using Azure Artifacts with npm, make sure you've installed the prerequisites. -1. Follow the instructions in the **Project setup** to set up your project. +1. Under the **Project setup** section, select **Windows** or **Other** depending on your operating system, then follow the provided instructions to configure your config file and connect to your Azure Artifacts feed. - :::image type="content" source="media/npm-azure-devops-newnav.png" alt-text="Screenshot showing how to set up your project"::: + :::image type="content" source="media/npm-project-setup-server-2022-1.png" alt-text="A screenshot displaying 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-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). - -#### [Windows](#tab/Windows/) -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. +::: moniker range="azure-devops-2020" -```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. Copy the following code snippet to your .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] - //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**: - - ```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 - ``` +> [!NOTE] +> The `vsts-npm-auth` is not supported in Azure DevOps Server. -1. Generate a [personal access token](../organizations/accounts/use-personal-access-tokens-to-authenticate.md) with **packaging read and write** scopes. +1. Sign in to your Azure DevOps collection, and then navigate to your project. -1. Encode your newly generated personal access token as follows: +1. Select **Artifacts**, select your feed from the dropdown menu, and then select **Connect to feed**. - 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. In the left navigation pane, select **npm**. If this is your first time using Azure Artifacts with npm, make sure you've installed the prerequisites. - 1. Paste your personal access token, and then press **Enter**. - - 1. Copy the Base64 encoded value. +1. Under the **Project setup** section, select **Windows** or **Other** depending on your operating system, then follow the provided instructions to configure your config file and connect to your Azure Artifacts 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-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 -* * * - -::: moniker range="tfs-2018" +> [!IMPORTANT] +> Npm supports only a single `registry` setting in your *npmrc* file. To use multiple registries, you must use [upstream sources](npm/upstream-sources.md) or [scopes](npm/scopes.md). -## Connect to feed +## Publish packages to your feed -1. Select **Packages**, and then select **Connect to feed**. +To successfully run the publish command, you must first authenticate with your feed. If you haven’t done this yet, follow the steps in the [Connect to a feed](#connect-to-a-feed) section then continue with the instructions below. -2. Select **npm**. +- In your project directory, run the following command to publish the npm package defined in your *package.json*: -3. Select **Generate npm credentials**. Copy the credentials and add them to your .npmrc file. + ``` + npm publish + ``` - :::image type="content" source="./media/tfs2018-connect-to-npm-feed.png" alt-text="Screenshot showing how generate credentials"::: +> [!IMPORTANT] +> Using the `publishConfig` property to override the registry configuration at publish time is not supported. -::: moniker-end +## Restore packages from your feed -## Publish packages +To successfully run the restore command, you must first authenticate with your feed. If you haven’t done this yet, follow the steps in the [Connect to a feed](#connect-to-a-feed) section then continue with the instructions below. -To publish your npm package, run the following command in your project directory +1. In your project directory, run the following command to restore all npm packages: -```Command -npm publish -``` + ``` + npm install + ``` -> [!IMPORTANT] -> Using the `publishConfig` property to override the registry config param at publish-time is not supported. +1. To restore a specific npm package, run the following command from your project directory: -## Restore packages + ``` + npm install --save + ``` -To restore an npm package, run the following command in your project directory +## Related content -```Command -npm install --save -``` +- [Publish npm packages with Azure Pipelines (YAML/Classic)](../pipelines/artifacts/npm.md) -## Next steps +- [Use packages from npmjs.com](npm/upstream-sources.md) -> [!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) +- [Use npm audit](npm/npm-audit.md) diff --git a/docs/artifacts/get-started-nuget.md b/docs/artifacts/get-started-nuget.md index 3b1f5c9bf53..0631c8e12a2 100644 --- a/docs/artifacts/get-started-nuget.md +++ b/docs/artifacts/get-started-nuget.md @@ -1,98 +1,108 @@ --- -title: Get started with NuGet packages and Azure Artifacts -description: Use Azure Artifacts to publish and download NuGet packages from your feeds +title: Publish and download NuGet packages with Azure Artifacts +description: Learn how to use Azure Artifacts to publish and download NuGet packages. 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 -monikerRange: '<= azure-devops' +ms.date: 06/20/2025 +monikerRange: '>= azure-devops-2020' "recommendations": "true" --- -# Get started with NuGet packages in Azure Artifacts +# Publish and download NuGet packages with Azure Artifacts -[!INCLUDE [version-lt-eq-azure-devops](../includes/version-lt-eq-azure-devops.md)] +[!INCLUDE [version-gt-eq-2020](../includes/version-gt-eq-2020.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 feeds or public registries. Feeds can be either private, allowing you to share packages with specific users, or public, making your packages accessible to anyone on the internet. -In this article, you'll learn how to: - -> [!div class="checklist"] -> * Create a new feed -> * Set up your project and connect to your feed -> * Publish NuGet packages -> * Download packages from your feed +This article guides you through creating a feed, configuring your project, and publishing and downloading NuGet packages. ## 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. - -- Install the [latest NuGet version](https://www.nuget.org/downloads). - -- Install [Azure Artifacts Credential Provider](https://github.com/microsoft/artifacts-credprovider#azure-artifacts-credential-provider). +| **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 the [Azure Artifacts Credential Provider](https://github.com/microsoft/artifacts-credprovider).
- Install the [latest NuGet version](https://www.nuget.org/downloads). | ## Create a feed -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. - [!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 navigation pane. If this is your first time using Azure Artifacts with *Nuget.exe*, make sure you've installed the prerequisites. - :::image type="content" source="./media/connect-to-feed-azure-devops-newnav.png" alt-text="A screenshot showing the connect to feed button."::: +1. Follow the provided instructions under the **Project setup** section to set up your *nuget.config* file and connect to your Azure Artifacts 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. + :::image type="content" source="./media/project-setup.png" alt-text="A screenshot displaying how to set up your project and connect to your feed in Azure DevOps Services."::: -1. Follow the instructions provided in the **Project setup** section to configure your nuget.config file. +::: moniker-end - :::image type="content" source="./media/project-setup.png" alt-text="A screenshot showing how to set up your project."::: +::: moniker range="azure-devops-2020 || azure-devops-2022" -::: moniker-end +1. Sign in to your Azure DevOps server, and then go to your project. -::: moniker range="tfs-2018" +1. Select **Artifacts**, and then select your feed from the dropdown menu. -1. Navigate to your project `http://ServerName:8080/tfs/DefaultCollection/`. +1. Select **Connect to Feed**, and then select **NuGet.exe** from the left navigation pane. -1. Select **Build and Release** > **Packages**. +1. Follow the provided instructions under the **Project setup** section to set up your *nuget.config* file and connect to your Azure Artifacts feed. -1. Select your feed from the dropdown menu. + :::image type="content" source="./media/connect-to-feed-nuget-server-2020.png" alt-text="A screenshot displaying how to set up your project and connect to your feed in Azure DevOps Server 2020 and 2022."::: -1. Select **Connect to feed**. +::: moniker-end - :::image type="content" source="./media/connect-to-feed.png" alt-text="A screenshot showing the connect to feed button in TFS."::: +## Publish packages to your feed -1. Select **NuGet**, and then follow the instruction to connect to your feed. +To publish a package to your feed, run the following command. The `ApiKey` parameter is required, but you can use any arbitrary string as its value. - :::image type="content" source="./media/connect-to-nuget-feed-tfs.png" alt-text="A screenshot showing how to connect to your feed in TFS."::: +```CLI +nuget.exe push -Source -ApiKey key +``` -::: moniker-end +#### Examples -## Download packages +- **Project-scoped feed**: -[!INCLUDE [](includes/nuget/consume.md)] + ```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] -> Using NuGet Package Explorer to search for packages in upstreams is not supported. +> The `ApiKey` is required, but you can use any arbitrary value when publishing to Azure Artifacts feeds. -## Publish packages +## Download packages from your feed -Run the following command to publish your package to your feed. You can use any string for the *ApiKey* argument. +To restore packages from your feed, run the following command in your project directory: -```Command -nuget.exe push -Source -ApiKey key +```CLI +nuget.exe restore ``` -## Related articles +::: moniker range="azure-devops" + +> [!NOTE] +> Searching for packages in upstream sources using the NuGet Package Explorer is not supported. + +::: moniker-end + +## Related content + +- [Publish NuGet packages with Azure Pipelines (YAML/classic)](../pipelines/artifacts/nuget.md) + +- [Publish packages to NuGet.org](nuget/publish-to-nuget-org.md) -- [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 +- [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..140e8145a50 100644 --- a/docs/artifacts/how-to/delete-and-recover-packages.md +++ b/docs/artifacts/how-to/delete-and-recover-packages.md @@ -1,305 +1,252 @@ --- 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 -monikerRange: '<= azure-devops' +ms.custom: peer-review-program +ms.topic: how-to +ms.date: 03/13/2025 +monikerRange: '>= azure-devops-2020' "recommendations": "true" --- # Delete and recover packages -[!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] +[!INCLUDE [version-gt-eq-2020](../../includes/version-gt-eq-2020.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-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/follow-package-notifications.md b/docs/artifacts/how-to/follow-package-notifications.md index a029a5a3021..d6c4b2ea4be 100644 --- a/docs/artifacts/how-to/follow-package-notifications.md +++ b/docs/artifacts/how-to/follow-package-notifications.md @@ -4,12 +4,12 @@ description: How to follow a package and get notified every time a new version i ms.service: azure-devops-artifacts ms.topic: conceptual ms.date: 06/14/2022 -monikerRange: '<= azure-devops' +monikerRange: '>= azure-devops-2020' --- # Package notification -[!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] +[!INCLUDE [version-gt-eq-2020](../../includes/version-gt-eq-2020.md)] Notifications are a great tool to stay informed about specific changes within your project. In Azure Artifacts, when you follow a package you’ll be notified every time a new version of that package is published. A notification will be sent to your preferred email address with details about the new published version. The preferred email address is usually the email address you signed into Azure DevOps with, but you can change it from your profile page. 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..8fbefcded47 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, the **Build Service** for the project *(for example: projectName Build Service (orgName))* is assigned the **Feed and Upstream Reader (Collaborator)** role when a new feed is created. 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/increase-storage-limit.md b/docs/artifacts/includes/increase-storage-limit.md new file mode 100644 index 00000000000..652ae5a2bc3 --- /dev/null +++ b/docs/artifacts/includes/increase-storage-limit.md @@ -0,0 +1,18 @@ +--- +ms.topic: include +ms.service: azure-devops-artifacts +ms.manager: mijacobs +ms.author: rabououn +author: ramiMSFT +ms.date: 04/29/2025 +--- + +Azure Artifacts provides 2 GiB of free storage for each organization. Once your organization reaches the maximum storage limit, you won’t be able to publish new artifacts. To continue, you can either delete some of your existing artifacts or increase your storage limit by following these steps: + +1. [Set up billing for your organization](../../organizations/billing/set-up-billing-for-your-organization-vs.md#set-up-billing-for-your-organization). + +1. Sign in to your Azure DevOps organization, select **Organization settings** > **Billing**, and select **No limit, pay for what you use** from the **Usage limit** dropdown. + +1. Select **Save** when you're done. + + :::image type="content" source="../media/adjust-artifacts-usage-limit.png" alt-text="A screenshot displaying how to increase Artifacts storage limit."::: \ No newline at end of file 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..20f3b4d64c7 100644 --- a/docs/artifacts/includes/maven/pom-and-settings.md +++ b/docs/artifacts/includes/maven/pom-and-settings.md @@ -3,29 +3,121 @@ ms.topic: include ms.service: azure-devops-artifacts ms.author: rabououn author: ramiMSFT -ms.date: 10/04/2022 +ms.date: 07/01/2024 +ms.custom: sfi-image-nochange --- -::: 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..236f1710159 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 -monikerRange: '<= azure-devops' +ms.date: 11/14/2023 +monikerRange: '>= azure-devops-2020' "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)] +[!INCLUDE [version-gt-eq-2020](../../includes/version-gt-eq-2020.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](project-setup-maven.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..c284624e4df 100644 --- a/docs/artifacts/maven/gradle-plugins.md +++ b/docs/artifacts/maven/gradle-plugins.md @@ -4,13 +4,13 @@ description: How to add Gradle Plugins upstream source ms.service: azure-devops-artifacts ms.topic: conceptual ms.date: 03/11/2022 -monikerRange: '<= azure-devops' +monikerRange: '>= azure-devops-2020' "recommendations": "true" --- # Gradle Plugins upstream source -[!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] +[!INCLUDE [version-gt-eq-2020](../../includes/version-gt-eq-2020.md)] With Azure Artifacts feeds, you can enable upstream sources to include packages from different public registries such as Gradle Plugins. Once upstream sources are enabled on your feed, Azure Artifacts will save a copy of any package you install from upstream. Azure Artifacts also support other Maven upstream sources such as Maven Central, Google Maven Repository, and JitPack. @@ -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..7f617ea82eb 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 -monikerRange: '<= azure-devops' +ms.date: 06/11/2024 +monikerRange: '>= azure-devops-2020' +"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)] +[!INCLUDE [version-gt-eq-2020](../../includes/version-gt-eq-2020.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..c3016e01697 100644 --- a/docs/artifacts/maven/jitpack-upstream.md +++ b/docs/artifacts/maven/jitpack-upstream.md @@ -4,13 +4,13 @@ description: How to add JitPack upstream source ms.service: azure-devops-artifacts ms.topic: conceptual ms.date: 03/22/2022 -monikerRange: '<= azure-devops' +monikerRange: '>= azure-devops-2020' "recommendations": "true" --- # JitPack upstream source -[!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] +[!INCLUDE [version-gt-eq-2020](../../includes/version-gt-eq-2020.md)] With Azure Artifacts, you can consume packages from different public registries such as Maven Central and Google Maven Repository and JitPack. Once you enable upstream sources, Azure Artifacts will save a copy of any package you install from upstream. @@ -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/publish-package-maven.png b/docs/artifacts/maven/media/publish-package-maven.png new file mode 100644 index 00000000000..4cdda1ab2b9 Binary files /dev/null and b/docs/artifacts/maven/media/publish-package-maven.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 deleted file mode 100644 index 53ffdd1caca..00000000000 --- a/docs/artifacts/maven/pom-and-settings.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: Set up your Maven project -description: How to set up Maven client -ms.service: azure-devops-artifacts -ms.assetid: 944f45ee-baa3-45ba-8467-5e7ab2bc47cf -ms.topic: conceptual -ms.date: 10/04/2022 -monikerRange: '<= azure-devops' ---- - -# Set up your Maven project and connect to feed - -[!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] - -[!INCLUDE [](../includes/maven/pom-and-settings.md)] - -> [!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). diff --git a/docs/artifacts/maven/project-setup-gradle.md b/docs/artifacts/maven/project-setup-gradle.md new file mode 100644 index 00000000000..871f6ee56fb --- /dev/null +++ b/docs/artifacts/maven/project-setup-gradle.md @@ -0,0 +1,163 @@ +--- +title: Connect to an Azure Artifacts feed - Gradle +description: Learn how to set up your project and connect to an Azure Artifacts feed with Gradle. +ms.service: azure-devops-artifacts +ms.topic: how-to +ms.author: rabououn +author: ramiMSFT +ms.date: 05/08/2025 +monikerRange: '>= azure-devops-2020' +"recommendations": "true" +--- + +# Connect to an Azure Artifacts feed - Gradle + +[!INCLUDE [version-gt-eq-2020](../../includes/version-gt-eq-2020.md)] + +Azure Artifacts enables developers to manage project dependencies from a single feed while controlling who can view, publish, or install packages. This article walks you through setting up your project and connecting to an Azure Artifacts feed using Gradle. + +## 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-a-feed).
- Download and install [Gradle](https://docs.gradle.org/current/userguide/installation.html). | + +## Project setup + +# [Gradle 8.2 and above](#tab/newerversions) + +1. Make sure you've installed Gradle, then add the *Maven Settings plugin* to your *build.gradle* file: + + ```groovy + plugins { + id 'maven-publish' + } + ``` + +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**. + +1. Select **Gradle** from the left navigation pane. + +1. If you don't have a *build.gradle* file in the root of your project, create one and name it: *build.gradle*. + +1. Add the snippet from the **Project setup** section to your *build.gradle* file under both the **repositories** and **publishing.repositories** blocks. Your file should look similar to the following: + + ```groovy + repositories { + mavenCentral() + + maven { + url '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' + name '' + credentials(PasswordCredentials) + authentication { + basic(BasicAuthentication) + } + } + } + } + ``` + +1. Generate a [Personal Access Token](../../organizations/accounts/use-personal-access-tokens-to-authenticate.md#create-a-pat) with **Packaging** > **Read & write** scopes, Copy it to your clipboard; you’ll use it in the next step. + +1. Open the *gradle.properties* file in the *.gradle* directory of your home folder (~/.gradle/gradle.properties). If it doesn’t exist, create a new file, then add the snippet from the **Project setup** section replacing the placeholder with the personal access token you just created: + + ``` + ## Substitute FEED_NAME with the same name used in your build.gradle + ## The username value can be any non-blank string + [FEED_NAME]Username=[ORGANIZATION_NAME] + [FEED_NAME]Password=[PERSONAL_ACCESS_TOKEN] + ``` + +# [Older versions](#tab/olderversions) + +1. Make sure you've installed Gradle, then add the *Maven Settings plugin* to your *build.gradle* file: + + ```groovy + plugins { + id 'net.linguica.maven-settings' version '0.5' + id 'maven-publish' + } + ``` + +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**. + +1. Select **Gradle** from the left navigation pane. + +1. If you don't have a *build.gradle* file in the root of your project, create one and name it: *build.gradle*. + +1. Add the snippet from the **Project setup** section to your *build.gradle* file under both the **repositories** and **publishing.repositories** blocks. Your file should look similar to the following: + + ```groovy + publishing { + publications { + library(MavenPublication) { + from components.java + } + } + + repositories { + maven { + url 'https://pkgs.dev.azure.com///_packaging//maven/v1' + name '' + authentication { + basic(BasicAuthentication) + } + } + } + } + + repositories { + maven { + url 'https://pkgs.dev.azure.com///_packaging//maven/v1' + name '' + authentication { + basic(BasicAuthentication) + } + } + } + ``` + +1. Generate a [Personal Access Token](../../organizations/accounts/use-personal-access-tokens-to-authenticate.md#create-a-pat) with **Packaging** > **Read & write** scopes, Copy it to your clipboard; you’ll use it in the next step. + +1. Open the *settings.xml* file in the *.m2* directory of your home folder (*~/.m2/settings.xml* - MacOS/Linux, *Users\\.m2\settings.xml* - Windows). If it doesn’t exist, create a new file, then add the following snippet, replacing the placeholders with your feed name, organization name, and the personal access token you created earlier. + + ```xml + + [FEED_NAME] + [ORGANIZATION_NAME] + [PERSONAL_ACCESS_TOKEN] + + ``` + +--- + +## Related content + +- [Publish artifacts with Gradle](publish-with-gradle.md) + +- [Restore Maven packages](install.md) + +- [Use packages from Maven Central](upstream-sources.md) diff --git a/docs/artifacts/maven/project-setup-maven.md b/docs/artifacts/maven/project-setup-maven.md new file mode 100644 index 00000000000..bb36c4f192c --- /dev/null +++ b/docs/artifacts/maven/project-setup-maven.md @@ -0,0 +1,141 @@ +--- +title: Connect your Maven project to an Azure Artifacts feed +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: how-to +ms.date: 05/05/2025 +monikerRange: '>= azure-devops-2020' +"recommendations": "true" +--- + +# Connect to an Azure Artifacts feed - Maven + +[!INCLUDE [version-gt-eq-2020](../../includes/version-gt-eq-2020.md)] + +Azure Artifacts enables developers to publish and restore Maven packages from feeds and public registries such as Maven Central and Google Maven Repository. This article walks you through setting up your Maven 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).
- An Azure Artifacts [feed](../get-started-nuget.md#create-a-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**, select your feed from the dropdown menu, and then select **Connect to feed**. + +1. In the left navigation pane, select **Maven**. Make sure you've installed the prerequisites, if not, select **Get the tools** in the top-right corner to download and install them. + +1. In the **Project setup** section, copy the `repository` snippet and add it to your *pom.xml* file within the `` and `distributionManagement>` sections. Your file should resemble the following: + + ```xml + + + FEED_NAME + https://pkgs.dev.azure.com///_packaging//maven/v1 + + true + + + true + + + + + + FEED_NAME + https://pkgs.dev.azure.com///_packaging//maven/v1 + + true + + + true + + + + ``` + +1. Add the provided snippet to your local *settings.xml* (located in *${user.home}/.m2*): + + ```xml + + + FEED_NAME + + [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** scopes, and paste it into the `` tag in your *settings.xml* file. + +::: 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**, select your feed from the dropdown menu, and then select **Connect to feed**. + +1. In the left navigation pane, select **Maven**. Make sure you've installed the prerequisites, if not, select **Get the tools** in the top-right corner to download and install them. + +1. In the **Project setup** section, copy the `repository` snippet and add it to your *pom.xml* file within the `` and `distributionManagement>` sections. Your file should resemble the following: + + ```xml + + + FEED_NAME + http://///_packaging//maven/v1 + + true + + + true + + + + + + FEED_NAME + http://///_packaging//maven/v1 + + true + + + true + + + + ``` + +1. Add the provided snippet to your local *settings.xml* (located in *${user.home}/.m2*): + + ```xml + + + FEED_NAME + + [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** scopes, and paste it into the `` tag in your *settings.xml* file. + +::: moniker-end + +> [!TIP] +> If your `settings.xml` file is shared across your team, you can use Maven to [encrypt your passwords](https://maven.apache.org/guides/mini/guide-encryption.html). + +## Related content + +- [Restore Maven packages](install.md) + +- [Use packages from Maven Central](upstream-sources.md) + +- [Use packages from Google Maven Repository](google-maven.md) diff --git a/docs/artifacts/maven/publish-packages-maven.md b/docs/artifacts/maven/publish-packages-maven.md new file mode 100644 index 00000000000..ab4fbecbb88 --- /dev/null +++ b/docs/artifacts/maven/publish-packages-maven.md @@ -0,0 +1,59 @@ +--- +title: Publish Maven packages to an Azure Artifacts feed +description: Learn how to connect to a feed and publish your Maven packages. +ms.service: azure-devops-artifacts +ms.topic: how-to +ms.author: rabououn +author: ramiMSFT +ms.date: 05/14/2025 +monikerRange: '>= azure-devops-2020' +"recommendations": "true" +--- + +# Publish Maven packages to an Azure Artifacts feed + +[!INCLUDE [version-gt-eq-2020](../../includes/version-gt-eq-2020.md)] + +Azure Artifacts provides a centralized way to host and manage your packages in a single feed. This article guides you through connecting to an Azure Artifacts feed and publishing your Maven 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](https://maven.apache.org/download.cgi) and [Install](https://maven.apache.org/install.html) Maven. | + +## Create a feed + +If you already have a feed, you can skip this section. Otherwise, follow the steps below to create a new feed: + +1. Sign in to your Azure DevOps organization, and navigate to your project. + +1. Select **Artifacts**, and then select **Create Feed**. + +1. Enter a **Name** for your feed, choose its **Visibility**, then select its **Scope**. To include packages from public registries, select the **Upstream sources** checkbox. + +1. Select **Create** when you're done. + +## Publish packages + +1. If you haven’t already authenticated with your feed, follow the steps in [Project setup](project-setup-maven.md) to connect to your feed. + +1. Run the following command in your project directory to publish your package: + + ``` + mvn deploy + ``` + +1. Once published, navigate to your feed. You should see your packages listed, as shown in the example below: + + :::image type="content" source="media/publish-package-maven.png" alt-text="A screenshot displaying a Maven package successfully published to the feed."::: + + +## Related content + +- [Publish packages - Gradle](publish-with-gradle.md) + +- [Restore Maven packages](install.md) + +- [Use packages from Maven Central](upstream-sources.md) + diff --git a/docs/artifacts/maven/publish-with-gradle.md b/docs/artifacts/maven/publish-with-gradle.md index dd822397c0a..f0c92c77046 100644 --- a/docs/artifacts/maven/publish-with-gradle.md +++ b/docs/artifacts/maven/publish-with-gradle.md @@ -1,129 +1,57 @@ --- -title: Publish a Maven artifact using Gradle -description: How to publish Maven artifacts using Gradle +title: Publish artifacts with 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.topic: how-to +ms.date: 05/12/2025 ms.author: rabououn author: ramiMSFT -monikerRange: '<= azure-devops' +monikerRange: '>= azure-devops-2020' "recommendations": "true" --- -# Publish Maven artifacts using Gradle +# Publish packages - Gradle -[!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] +[!INCLUDE [version-gt-eq-2020](../../includes/version-gt-eq-2020.md)] -In this article, you will learn how to connect to an Azure Artifacts feed and publish Maven artifacts using Gradle. +Azure Artifacts enables developers to manage all their dependencies in one place by storing multiple package types in a single feed. This article walks you through connecting to an Azure Artifacts feed and publishing packages using Gradle. ## 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).
- Download and install [Gradle](https://docs.gradle.org/current/userguide/installation.html). | -- An Azure Artifacts feed. [Create a feed](../concepts/feeds.md#create-public-feeds) if you don't have one already. +## Create a feed -- 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). - -## 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: - -```groovy -plugins { - id "net.linguica.maven-settings" version "0.5" -} -``` - -### Create a personal access token +Azure Artifacts recommends using one feed for consuming packages and a separate one for publishing your internal packages. If you already have a feed, you can skip this step. Otherwise, follow these steps to create a new feed: 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="Screenshot showing how to create a personal access token"::: - -1. Select **New Token**, and then fill out the required fields. Make sure you select the **Packaging** > **Read & write** scope. +1. Select **Artifacts**, then select **Create Feed**. -1. Select **Create** when you are done. Copy your token and save it in a secure location. +1. Provide a **Name** for your feed and set its **Visibility**, then select a **Scope** for your feed. If you'd like to include packages from public registries, check the **Upstream sources** checkbox. - :::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."::: +1. Select **Create** when you're done. -### Configure build.gradle +## Publish packages -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 you haven't authenticated with your feed yet, follow the steps in [Project setup](project-setup-gradle.md) to set up your config files and authenticate with your feed. -1. Add the following section to your *build.gradle* file in both the **repositories** and **publishing.repositories** containers. +1. In your project directory, run the following command to publish your package: - ```groovy - maven { - url '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 - repositories { - maven { - url 'https://pkgs.dev.azure.com///_packaging//maven/v1' - name '' - authentication { - basic(BasicAuthentication) - } - } - } - ``` - -### 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. - - ```xml - - [FEED_NAME] - [ORGANIZATION_NAME] - [PERSONAL_ACCESS_TOKEN] - + gradle publish ``` -## Publish artifacts +1. Once published, navigate to your feed. You should see your packages listed, as shown in the example below: + + :::image type="content" source="media/publish-package-gradle.png" alt-text="A screenshot displaying a package successfully published to the feed."::: -Run the following command in an elevated command prompt to publish your package to your feed. Your new package will be named: *groupId:artifactId*. +## Related content -```Command -gradle publish -``` +- [Restore Maven packages](./install.md) -## Related articles +- [Use packages from Maven Central](upstream-sources.md) -- [Install Maven Artifacts](./install.md) -- [Use packages from Maven Central](./upstream-sources.md) -- [Google Maven Repository upstream source](./google-maven.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..b1b94335f40 100644 --- a/docs/artifacts/maven/upstream-sources.md +++ b/docs/artifacts/maven/upstream-sources.md @@ -1,51 +1,96 @@ --- 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 -monikerRange: '<= azure-devops' +ms.date: 11/10/2023 +monikerRange: '>= azure-devops-2020' "recommendations": "true" --- # Use packages from Maven Central -[!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] +[!INCLUDE [version-gt-eq-2020](../../includes/version-gt-eq-2020.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](project-setup-maven.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-badge-new-ui.png b/docs/artifacts/media/create-badge-new-ui.png index c1471b2149f..e51a3d7660c 100644 Binary files a/docs/artifacts/media/create-badge-new-ui.png and b/docs/artifacts/media/create-badge-new-ui.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-package-badges.png b/docs/artifacts/media/enable-package-badges.png index f3388eae30a..1c4aee1756e 100644 Binary files a/docs/artifacts/media/enable-package-badges.png and b/docs/artifacts/media/enable-package-badges.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/new-feed-with-upstream-source.png b/docs/artifacts/media/new-feed-with-upstream-source.png new file mode 100644 index 00000000000..b889de39963 Binary files /dev/null and b/docs/artifacts/media/new-feed-with-upstream-source.png 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/package-badge-setup.png b/docs/artifacts/media/package-badge-setup.png index 30d5441da46..52d5fb81787 100644 Binary files a/docs/artifacts/media/package-badge-setup.png and b/docs/artifacts/media/package-badge-setup.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..93c0a5b7b2d 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-a-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..5a152d853fa 100644 --- a/docs/artifacts/npm/npmrc.md +++ b/docs/artifacts/npm/npmrc.md @@ -1,95 +1,87 @@ --- -title: Set up your client's npmrc -description: How to set up your project and connect to Azure Artifacts feeds +title: Connect to an Azure Artifacts feed - npm +description: Learn how to set up your npm project and connect to an Azure Artifacts feed. ms.assetid: A5364E3A-3918-4318-AAE0-430EA91AD5F1 ms.service: azure-devops-artifacts ms.custom: engagement-fy23 ms.topic: conceptual -ms.date: 04/04/2023 -monikerRange: '<= azure-devops' +ms.date: 07/08/2025 +monikerRange: '>= azure-devops-2020' +"recommendations": "true" --- -# Set up your project and connect to Azure Artifacts +# Connect to an Azure Artifacts feed - npm -[!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] +[!INCLUDE [version-gt-eq-2020](../../includes/version-gt-eq-2020.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 packages from various sources, including public registries like *npmjs.com* and private feeds. To authenticate with Azure Artifacts, you need to configure your *.npmrc* config file. This file stores feed URLs and credentials used by npm, and it allows you to customize client behavior such as setting up proxies, defining default package locations, or configuring access to private 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: +| **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-npm.md#create-a-feed)
- [Download and install Node.js and npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm).| -### [Windows](#tab/windows/) - -::: moniker range="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 **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."::: +Azure Artifacts recommends using two separate *.npmrc* configuration files. One should be stored locally to store your credentials, while the other should be added to your project directory alongside your *package.json* to define your feed URL. This approach allows you to share your project-level configuration without exposing sensitive information. -1. Select **npm** from the left navigation pane. +To set up the credentials file, create or update the *.npmrc* file and include all necessary registry credentials. This enables the npm client to easily access your credentials for authentication. -1. If this is the first time using Azure Artifacts with npm, select **Get the tools** and follow the instructions to install the prerequisites. +The following steps guide you through setting up the project-level configuration file. Select the tab that corresponds to your development environment: -1. Follow the instructions in **Project setup** to set up your config file. +::: moniker range="< azure-devops" - :::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."::: +> [!NOTE] +> `vsts-npm-auth` is not supported in Azure DevOps Server. ::: moniker-end -::: moniker range="azure-devops-2019 || azure-devops-2020 || azure-devops-2022" - -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. +::: 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. +### [Windows](#tab/windows/) -1. Follow the instructions in **Project setup** to set up your config file. +1. Sign in to your Azure DevOps organization, and then navigate to your project. - :::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."::: +1. Select **Artifacts**, and then select your feed from the dropdown menu. -::: moniker-end +1. Select **Connect to Feed** and then select **npm** from the left navigation pane. -::: moniker range="tfs-2018" +1. Add a *.npmrc* to your project, in the same directory as your *package.json* and paste the provided snippet from the **Project setup** section into the file. -1. Select **Build and Release**. + :::image type="content" source="../media/npm-project-setup-azure-devops.png" alt-text="A screenshot displaying how to set up your npm project and connect to a feed."::: -1. Select **Packages**, and then select **Connect to feed**. +1. Run the following command to get an Azure Artifacts token added to your user-level *.npmrc* file. You don’t need to run this every time—npm will return a **401 Unauthorized** error when it’s time to refresh the token. - :::image type="content" source="../media/connect-to-feed.png" alt-text="Screenshot showing how to connect to a feed in TFS."::: - -1. Select **npm** from the left navigation pane. + ``` + vsts-npm-auth -config .npmrc + ``` -1. Follow the instructions provided in the **Other** tab to set up your project. +### [Other](#tab/other/) -::: moniker-end +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. -> [!TIP] -> Using multiple registries in .npmrc files is supported with [scopes](..//npm/scopes.md) and [upstream sources](../concepts/upstream-sources.md). +1. Select **Connect to Feed** and then select **npm** from the left navigation pane. -### [Other](#tab/other/) +1. Add a *.npmrc* file to your project's directory. This should be the same directory where your *package.json* file is located. -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. Paste the snippet provided in the **Project setup** section into your *.npmrc* file. Your file should look similar to the following: - ```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 +94,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 +107,182 @@ 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. When prompted, paste your personal access token (PAT) and press **Enter**. The script will return a Base64-encoded version of your PAT, copy that value to use in the next step. - ```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 using Linux or macOS, you can run the following command in your terminal to convert your personal access token (PAT) to a Base64-encoded string. Copy the resulting value to use in the next step. - - **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-level *.npmrc* file with the Base64-encoded personal access token you generated in the previous step. * * * -> [!NOTE] -> `vsts-npm-auth` is not supported in TFS and Azure DevOps Server. - -## Pipeline authentication +::: moniker-end -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. +::: moniker range="azure-devops-2022" -### [Classic](#tab/classic) +### [Windows](#tab/windows/) -::: moniker range=">= azure-devops-2019" +1. Sign in to your Azure DevOps collection, and then navigate to your project. -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**. + + :::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. Select **Azure Pipelines**, and then select your pipeline definition. +1. Select **npm** from the left, and then follow the steps in the **Project setup** section to configure your .npmrc. file and authenticate with your feed. -1. Select **Edit** to modify your pipeline. + :::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 `+` to add a task to your pipeline. +### [Other](#tab/other/) - :::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."::: +1. Sign in to your Azure DevOps collection, and then navigate to your project. -1. Search for the **npm Authenticate** task, and then select **Add** to add it to your pipeline. +1. Select **Artifacts**, and then select your feed from the dropdown menu. - :::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."::: +1. Select **Connect to Feed** and then select **npm** from the left navigation pane. -1. Select your *.npmrc* file. +1. Add a *.npmrc* file in your project's directory, in the same directory as your *package.json* file, and paste the snippet provided in the **Project setup** section into your *.npmrc* file. Your file should look similar to the following: - :::image type="content" source="../media/build-definition/build-definition-npm-auth-task-file.png" alt-text="Screenshot showing how to add your *.npmrc* file."::: + ``` + registry=http://///_packaging//npm/registry/ + + always-auth=true + ``` -1. Select **Save & queue** when you're done. +### Setup credentials -::: moniker-end +1. Copy the following snippet and paste it into your user-level *.npmrc* file: -::: moniker range="tfs-2018" + - **Collection-scoped feed**: -1. Select **Build and Release**, and then select **Builds**. + ``` + ; 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="../../pipelines/media/get-started-designer/navigate-to-builds-tab-tfs-2018-2.png" alt-text="Screenshot showing how to access your builds in TFS."::: + - **Project-scoped feed**: -1. Select your pipeline, and then select **Edit**. + ``` + ; 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. Select `+` to add a task to your pipeline. +1. Generate a [personal access token](../../organizations/accounts/use-personal-access-tokens-to-authenticate.md) with **packaging read and write** scopes. - :::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."::: +1. Run the following command in a command prompt window. When prompted, paste your personal access token and press **Enter**. The script will return a Base64-encoded version of your PAT, copy that value to use in the next step. -1. Search for the **npm Authenticate** task, and then select **Add** to add it to your pipeline. + ``` + 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/build-definition/build-definition-npm-auth-task-phase.png" alt-text="Screenshot showing the npm authenticate task."::: +1. Replace the placeholders *[BASE64_ENCODED_PERSONAL_ACCESS_TOKEN]* in your user-level *.npmrc* file with the Base64-encoded personal access token you generated in the previous step. -1. Select your *.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."::: +::: moniker-end -1. Select **Save & queue** when you're done. +::: moniker range="azure-devops-2020" -::: moniker-end +### [Windows](#tab/windows/) -### [YAML](#tab/yaml) +1. Sign in to your Azure DevOps collection, and then navigate to your project. -```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. 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 **npm** from the left, and then follow the steps in the **Project setup** section to configure your .npmrc. file and authenticate with your feed. -> [!NOTE] -> To grant your pipeline access to your feed, make sure you set the build service role to **Contributor** in your feed settings. + :::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="../media/project-collection-contributor.png" alt-text="A screenshot showing the build service roles in feed settings."::: +### [Other](#tab/other/) -> [!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). +1. Sign in to your Azure DevOps collection, and then navigate to your project. -## Troubleshoot +1. Select **Artifacts**, and then select your feed from the dropdown menu. -##### vsts-npm-auth is not recognized +1. Select **Connect to Feed** and then select **npm** from the left navigation pane. -If you encounter the following error while running your project: +1. Add a *.npmrc* file in your project's directory, in the same directory as your *package.json* file, and paste the snippet provided in the **Project setup** section into your *.npmrc* file. Your file should look similar to the following: -- 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.` + ``` + registry=http://///_packaging//npm/registry/ + + always-auth=true + ``` -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. +> [!NOTE] +> For Debian, Ubuntu, and other community or enterprise distributions such as Fedora or Redhat make sure you've installed the prerequisites from the [NodeSource distributions repository](https://github.com/nodesource/distributions). -:::image type="content" source="./media/node-setup.png" alt-text="A Screenshot showing how to set up node.js."::: +### Setup credentials -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. +1. Copy the following snippet and paste it into your user-level *.npmrc* file: -##### Unable to authenticate + - **Collection-scoped feed**: -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. + ``` + ; 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 + ``` -```Command -vsts-npm-auth -config .npmrc -F -``` + - **Project-scoped feed**: -##### Reset vsts-npm-auth + ``` + ; 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 + ``` -Follow the steps below to modify/reset your vsts-npm-auth credentials: +1. Generate a [personal access token](../../organizations/accounts/use-personal-access-tokens-to-authenticate.md) with **packaging read and write** scopes. -- Uninstall vsts-npm-auth. +1. Run the following command in a command prompt window. When prompted, paste your personal access token and press **Enter**. The script will return a Base64-encoded version of your PAT, copy that value to use in the next step. - ```command - npm uninstall -g vsts-npm-auth + ``` + 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(); })" ``` -- Clear your npm cache. +1. Replace the placeholders *[BASE64_ENCODED_PERSONAL_ACCESS_TOKEN]* in your user-level *.npmrc* file with the Base64-encoded personal access token you generated in the previous step. - ```command - npm cache clean --force - ``` +* * * -- Delete your *.npmrc* file. +::: moniker-end -- Reinstall vsts-npm-auth. +> [!TIP] +> Using multiple registries in *.npmrc* files is supported with [scopes](..//npm/scopes.md) and [upstream sources](../concepts/upstream-sources.md). - ```command - npm install -g vsts-npm-auth --registry https://registry.npmjs.com --always-auth false - ``` +## Related content + +- [Publish npm packages (CLI)](publish.md) -## Related articles +- [Restore npm packages](restore-npm-packages.md) -- [Publish npm packages (YAML/Classic)](../../pipelines/artifacts/npm.md) -- [Use npm scopes](./scopes.md) -- [Use npm audit](./npm-audit.md) +- [Publish npm packages with Azure Pipelines (YAML/Classic)](../../pipelines/artifacts/npm.md) diff --git a/docs/artifacts/npm/publish.md b/docs/artifacts/npm/publish.md index 67a05b80d02..ce75d34179e 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-a-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-a-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..639b0fd91c7 --- /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-2020' +--- + +# Restore npm packages from the command line + +[!INCLUDE [version-gt-eq-2020](../../includes/version-gt-eq-2020.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-a-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-a-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..51a2899dd20 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 -monikerRange: '<= azure-devops' +ms.date: 09/11/2023 +monikerRange: '>= azure-devops-2020' --- -# Npm scopes +# Use Npm scopes in Azure Artifacts -[!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] +[!INCLUDE [version-gt-eq-2020](../../includes/version-gt-eq-2020.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..ea31ba86843 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 -monikerRange: '<= azure-devops' +ms.date: 11/29/2023 +monikerRange: '>= azure-devops-2020' +"recommendations": "true" --- # Use packages from npmjs.com -[!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] +[!INCLUDE [version-gt-eq-2020](../../includes/version-gt-eq-2020.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-a-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..706067cdb4a 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)] +[!INCLUDE [version-gt-eq-2020](../../includes/version-gt-eq-2020.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-a-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,70 @@ 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"::: ::: 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**: -- **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 +``` - ```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 - ``` -## Publish packages from external sources +> [!NOTE] +> The `api-key` is required, but you can provide any string as its value when publishing to an Azure Artifacts feed. -1. Create a [personal access token](../../organizations/accounts/use-personal-access-tokens-to-authenticate.md) (PAT) with **packaging read and write** scope. +## Publish packages to a feed in another organization -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. +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. - ```Command - dotnet nuget add source https://pkgs.dev.azure.com///_packaging//nuget/v3/index.json --name --username --password --configfile - ``` +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. Publish your package: +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 - dotnet nuget push --source --api-key + ```CLI + dotnet nuget add source https://pkgs.dev.azure.com///_packaging//nuget/v3/index.json --name --username --password --configfile ``` -- **Example**: +1. Run the following command to publish your package: - ```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 push --source --api-key ``` -## Restore packages +**Example**: -To restore your packages, run the following command in an elevated command prompt. The `--interactive` flag is used to prompt the user for credentials. +```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 -```Command -dotnet restore --interactive +dotnet nuget push --source MySource --api-key AZ nupkgs/mypackage.1.1.0.nupkg ``` -## Related articles +> [!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). + + +## 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..5ecdc39e054 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-a-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..52874b8d5f8 --- /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-2020' +--- + +# Install NuGet packages with Visual Studio + +[!INCLUDE [version-gt-eq-2020](../../includes/version-gt-eq-2020.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-a-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..5611801295b 100644 --- a/docs/artifacts/nuget/move-from-fileshares.md +++ b/docs/artifacts/nuget/move-from-fileshares.md @@ -5,13 +5,13 @@ ms.assetid: E45D2856-222F-444B-9E0C-A04B6FE93494 ms.service: azure-devops-artifacts ms.topic: conceptual ms.date: 06/16/2023 -monikerRange: '<= azure-devops' +monikerRange: '>= azure-devops-2020' "recommendations": "true" --- # Migrate from file shares to Azure Artifacts -[!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] +[!INCLUDE [version-gt-eq-2020](../../includes/version-gt-eq-2020.md)] Using Azure Artifacts, you can streamline package management to enhance collaboration, ensure package integrity, and leverage various capabilities such as versioning, access control, and feed management. diff --git a/docs/artifacts/nuget/nuget-exe.md b/docs/artifacts/nuget/nuget-exe.md index 45075b84666..e3f5794cd48 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 -monikerRange: '<= azure-devops' +ms.topic: how-to +ms.date: 04/08/2025 +monikerRange: '>= azure-devops-2020' +"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)] +[!INCLUDE [version-gt-eq-2020](../../includes/version-gt-eq-2020.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-a-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-to-nuget-org.md b/docs/artifacts/nuget/publish-to-nuget-org.md index 4d300a564f4..81d3de32e40 100644 --- a/docs/artifacts/nuget/publish-to-nuget-org.md +++ b/docs/artifacts/nuget/publish-to-nuget-org.md @@ -5,13 +5,13 @@ ms.service: azure-devops-artifacts ms.author: rabououn author: ramiMSFT ms.date: 4/01/2021 -monikerRange: '<= azure-devops' +monikerRange: '>= azure-devops-2020' "recommendations": "true" --- # Publish packages to NuGet.org -[!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] +[!INCLUDE [version-gt-eq-2020](../../includes/version-gt-eq-2020.md)] NuGet.org is a package manager that enables developers to share reusable code. A NuGet package is a compressed file with `.nupkg` extension that contains compiled code that can be consumed in other projects. Packages hosted in NuGet.org are available to all developers around the world. diff --git a/docs/artifacts/nuget/publish.md b/docs/artifacts/nuget/publish.md index bd295d707ab..28a56cc7f14 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 -monikerRange: '<= azure-devops' +ms.topic: tutorial +ms.date: 01/14/2025 +monikerRange: '>= azure-devops-2020' --- -# 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)] +[!INCLUDE [version-gt-eq-2020](../../includes/version-gt-eq-2020.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-a-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..14f6c6b6058 --- /dev/null +++ b/docs/artifacts/nuget/restore-nuget-packages-dotnet.md @@ -0,0 +1,85 @@ +--- +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-gt-eq-2020](../../includes/version-gt-eq-2020.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-a-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" + +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..765bc2f938e --- /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-2020' +--- + +# Restore NuGet packages from the command line (NuGet.exe) + +[!INCLUDE [version-gt-eq-2020](../../includes/version-gt-eq-2020.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-a-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..42b91f71026 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 -monikerRange: '<= azure-devops' +ms.date: 04/16/2024 +monikerRange: '>= azure-devops-2020' "recommendations": "true" --- -# NuGet.org upstream source +# Use packages from NuGet Gallery -[!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] +[!INCLUDE [version-gt-eq-2020](../../includes/version-gt-eq-2020.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..eb1f732ed80 100644 --- a/docs/artifacts/package-badges.md +++ b/docs/artifacts/package-badges.md @@ -1,57 +1,55 @@ --- -title: Share your Artifacts with package badges -description: How to share your packages with package badges +title: Share packages using package badges in Azure Artifacts +description: Learn how to share your packages using package badges in Azure Artifacts. ms.assetid: 60a3f33a-d8bc-436a-a676-c1bd4b3066e7 ms.service: azure-devops-artifacts -ms.topic: conceptual -ms.date: 06/21/2022 -monikerRange: '<= azure-devops' +ms.topic: how-to +ms.date: 06/03/2025 +monikerRange: '>= azure-devops-2020' --- -# Share your Artifacts with package badges +# Share packages using package badges in Azure Artifacts -[!INCLUDE [version-lt-eq-azure-devops](../includes/version-lt-eq-azure-devops.md)] +[!INCLUDE [version-gt-eq-2020](../includes/version-gt-eq-2020.md)] -With Azure Artifacts, you can share your packages anywhere you can share an image by using package badges. You can embed package badges directly into your project's home page or in any Markdown file for your customers to easily find and download your packages. +Azure Artifacts enables developers to host various types of packages in a single feed and share them based on visibility settings, within a team, across an organization, or with external users. -## Enable package sharing +One way to make your packages more discoverable is by using package badges; small embedded images that display key details like package type and version. You can add these badges to your project’s homepage or any Markdown file, making it easy for others to find and download your packages. -> [!NOTE] -> You must be a feed administrator to enable package sharing. - -::: moniker range=">= azure-devops-2019" - -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**. +## Prerequisites - :::image type="content" source="media/feed-settings.png" alt-text="A screenshot showing how to navigate to the feed settings"::: +| **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). | -1. Find the **Package sharing** section and select the checkbox to **Enable package badges**. +## Enable package badges - :::image type="content" source="media\enable-package-badges.png" alt-text="A screenshot showing how to enable package badges"::: - -::: moniker-end +> [!NOTE] +> You must be a **Feed Administrator** to enable package badges. See [Manage permissions](feeds/feed-permissions.md) for more details. -::: moniker range="tfs-2018" +Before you can start using package badges, you must first enable them in your feed settings: -1. Select **Build and Release**, and then select **Packages**. +1. Sign in to your Azure DevOps organization, and then navigate to your project. -1. Select the gear icon ![gear icon](../media/icons/gear-icon.png) to access the **Feed settings**. +1. Select **Artifacts**, select your feed from the dropdown menu, and then select the gear icon ![gear icon](../media/icons/gear-icon.png) to access **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"::: + :::image type="content" source="media/feed-settings.png" alt-text="A screenshot displaying how to navigate to feed settings."::: -1. Select **Enable package badges**. This will enable the **Create badge** button for every package in that feed. +1. Under **Feed Details**, find the **Package sharing** section and check the **Enable package badges** checkbox. - :::image type="content" source="media/pm-create-badge.png" alt-text="A screenshot showing how to create a package badge in TFS."::: +1. Select **Save** when you're done. -::: moniker-end + :::image type="content" source="media\enable-package-badges.png" alt-text="A screenshot displaying how to enable package badges in Azure Artifacts."::: ## 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. +With package sharing enabled, you can now create a badge for any package in your feed. However, keep in mind that you can only create a badge for the latest version of each package. + +1. Sign in to your Azure DevOps organization, and then navigate to your project. -::: moniker range=">= azure-devops-2019" +1. Select **Artifacts**, select your feed from the dropdown menu, then select the package you want to create a badge for. -1. From within your feed, select your package and then select **Create badge**. +1. Under **Overview**, select the ellipsis button, and then select **Create badge**. :::image type="content" source="media/create-badge-new-ui.png" alt-text="A screenshot showing how to create a new package badge."::: @@ -59,24 +57,12 @@ With package-sharing enabled, you can create a badge for any package in your fee :::image type="content" source="media/package-badge-setup.png" alt-text="A screenshot showing the create a package badge panel."::: -1. You can now share your package by using the Markdown snippet or the direct image link. - -::: 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. You can now share your package by copying the Markdown snippet or the direct image link, and pasting it into your project home page or any markdowm file. -1. Share the Markdown snippet or the image link with your customers. +## Related content -::: moniker-end +- [Follow a package for publish alerts](how-to/follow-package-notifications.md) -## Related articles +- [Limits on package sizes and counts](reference/limits.md) -- [Limits of package sizes and counts](./reference/limits.md) -- [Package notifications](./how-to/follow-package-notifications.md) -- [Delete and recover packages](./how-to/delete-and-recover-packages.md) \ No newline at end of file +- [Delete and recover packages](how-to/delete-and-recover-packages.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..2124945ee73 --- /dev/null +++ b/docs/artifacts/quickstarts/download-universal-packages.md @@ -0,0 +1,108 @@ +--- +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-eq-azure-devops](../../includes/version-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 + ``` + +> [!NOTE] +> Azure Artifacts does not support a direct API endpoint to download Universal Packages. You must use the Azure CLI to download the package. + +## 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..ed303ead0e8 100644 --- a/docs/artifacts/quickstarts/python-packages.md +++ b/docs/artifacts/quickstarts/python-packages.md @@ -1,126 +1,132 @@ --- -title: Get started with Python packages in Azure Artifacts -description: Quickly start hosting python packages with Azure Artifacts +title: Publish and download Python packages with Azure Artifacts +description: Learn how to configure your project to publish and download Python packages with Azure Artifacts. ms.service: azure-devops-artifacts ms.topic: quickstart -ms.date: 01/19/2023 -monikerRange: '<= azure-devops' +ms.date: 07/02/2025 +monikerRange: "<=azure-devops" ms.custom: devx-track-python, py-fresh-zinc, engagement-fy23 "recommendations": "true" --- -# Get started with Python packages in Azure Artifacts +# Publish and download Python packages with 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 guides you through creating a feed, configuring your project, and managing Python packages in your 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/). | + +## Get the code + +1. If you don't have your own Python project, you can use the following sample Python project. Otherwise, you can skip to the next section: + + ``` + https://github.com/Azure-Samples/azure-stack-hub-flask-hello-world + ``` + +1. To build your wheel and source distribution, run the following commands in your project directory: + + ``` + pip install --upgrade build + python -m build + ``` + +1. If your Python project has a *setup.py* file, you can also build your package using: + + ``` + python setup.py sdist bdist_wheel + ``` ## Create a feed [!INCLUDE [](../includes/create-feed.md)] - -## Connect to feed -There are two primary ways to connect to a feed to publish or consume your Python packages: +## Connect to your feed -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). +#### [twine](#tab/twine) -> [!NOTE] -> **artifacts-keyring** is not supported on newer versions of Ubuntu. +1. Sign in to your Azure DevOps organization, and then navigate to your project. -## Use artifacts-keyring to set up authentication +1. Select **Artifacts**, select your feed from the dropdown menu, and then select **Connect to feed**. -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. +1. Under the **Python** section, select **twine**. -> [!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. If this is your first time using Azure Artifacts with twine, select **Get the tools** and follow the instructions to download Python and install Twine and the artifacts keyring. -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**: +1. Create a *pypirc* file in your home directory and paste the snippet provided in the **Project setup** section. Your file should look like this: - ```Command - pip install --index-url https://pkgs.dev.azure.com///_packaging//pypi/simple - ``` - - - **Organization scoped feed**: + ``` + [distutils] + Index-servers = + FEED_NAME - ```Command - pip install --index-url https://pkgs.dev.azure.com//_packaging//pypi/simple - ``` + [FEED_NAME] + Repository = https://pkgs.dev.azure.com/ORGANIZATION_NAME/PROJECT_NAME/_packaging/FEED_NAME/pypi/upload/ + ``` -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 - ``` +> [!NOTE] +> If your *.pypirc* file already includes credentials for the public PyPI index, we recommend removing the `[pypi]` section to avoid accidentally publishing private packages to PyPI. - - **Organization scoped feed**: - - ```Command - twine upload --repository-url https://pkgs.dev.azure.com//_packaging//pypi/upload - ``` +#### [pip](#tab/pip) -> [!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. +1. Sign in to your Azure DevOps organization, and then navigate to your project. -## Manually configure authentication +1. Select **Artifacts**, select your feed from the dropdown menu, and then select **Connect to feed**. -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. +1. Under the **Python** section, select **pip**. -1. Select **Artifacts**, and then select your feed then select **Connect to feed**. +1. If this is your first time using Azure Artifacts with pip, select **Get the tools** and follow the instructions to download Python, update pip, and install the keyring. - :::image type="content" source="../media/connect-to-feed-azure-devops-newnav.png" alt-text="A screenshot highlighting the connect to feed button."::: +1. [Create a virtual environment](https://docs.python.org/3/library/venv.html). -1. Select **pip** under the **Python** section. +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: - :::image type="content" source="media/pip-feed.png" alt-text="A screenshot highlighting the pip package type."::: + ``` + [global] + index-url=https://pkgs.dev.azure.com/ORGANIZATION_NAME/PROJECT_NAME/_packaging/FEED_NAME/pypi/simple/ + ``` -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 virtualenv](https://docs.python.org/3/library/venv.html), if you don't already have one. +## Publish packages to your feed -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. +1. In your project directory, run the following command to create source and wheel distributions: - - **Project scoped feed**: + ``` + python setup.py sdist bdist_wheel + + ``` - ``` - [global] - extra-index-url=https://:@pkgs.dev.azure.com///_packaging//pypi/simple/ - ``` +1. To publish your package, use the command below. Be sure to use the -r *FEED_NAME* flag to avoid accidentally publishing to PyPI: - - **Organization scoped feed**: + ``` + twine upload -r dist/* + ``` - ``` - [global] - extra-index-url=https://:@pkgs.dev.azure.com//_packaging//pypi/simple/ - ``` +## Install packages from your feed -1. Run the following command in your project directory to install your package. +1. To install packages from your feed, run the following command in your project directory: - ```Command - pip install + ``` + pip install ``` -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. +1. To install a specific package, replace the placeholder with the package name from your feed: -> [!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. + ``` + pip install + ``` -## Related articles +## Related content -- [Use feed views to share packages](../feeds/views.md) +- [Set up upstream sources](../how-to/set-up-upstream-sources.md) -- [Publish Python packages with Azure Pipelines](../../pipelines/artifacts/pypi.md). +- [Use packages from Python package index (PyPI)](../python/use-packages-from-pypi.md) -- [Build Python apps](../../pipelines/ecosystems/python.md). +- [Publish Python packages with Azure Pipelines YAML/Classic](../../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..211814bf525 100644 --- a/docs/artifacts/reference/artifactignore.md +++ b/docs/artifacts/reference/artifactignore.md @@ -1,46 +1,62 @@ --- 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: 05/19/2025 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 [PublishBuildArtifacts](/azure/devops/pipelines/tasks/reference/publish-build-artifacts-v1) task, use the [PublishPipelineArtifact](/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 `+` isn't 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 **/* !src/MyApp/bin/Release/**.* ``` -> [!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. +To include multiple files or folders when everything else is excluded, start with a blanket exclude pattern `(**/*)`, then add one `!` prefixed rule for each file or directory you want to keep. In the example below, the `dist` folder and all its contents along with `package.json` and `.npmrc` are included: -## Syntax +```artifactignore +# Exclude everything +**/* -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. +# Re-include the top-level dist folder, its contents, and the specific files +!dist/ +!dist/** +!package.json +!.npmrc +``` -> [!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. +> [!IMPORTANT] +> 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..2eb07341689 100644 --- a/docs/artifacts/reference/limits.md +++ b/docs/artifacts/reference/limits.md @@ -4,15 +4,18 @@ description: Package count and size limits in Azure Artifacts ms.service: azure-devops-artifacts ms.topic: conceptual ms.date: 02/25/2022 -monikerRange: '<= azure-devops' +monikerRange: '>= azure-devops-2020' --- # Package sizes and count limits -[!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] +[!INCLUDE [version-gt-eq-2020](../../includes/version-gt-eq-2020.md)] 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,27 @@ 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 MiB per file. Additionally, Azure Artifacts enforces a separate hard limit of 375 KB specifically for the *package.json* file. -- **Npm packages**: limited to 500 MB per file. +- **Maven packages**: limited to 500 MiB per file. -- **Maven packages**: limited to 500 MB 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 + +## Increase Artifacts storage limit + +[!INCLUDE [](../includes/increase-storage-limit.md)] ## Related articles diff --git a/docs/artifacts/start-using-azure-artifacts.md b/docs/artifacts/start-using-azure-artifacts.md index 521e900670f..b5f769c6fa6 100644 --- a/docs/artifacts/start-using-azure-artifacts.md +++ b/docs/artifacts/start-using-azure-artifacts.md @@ -1,152 +1,215 @@ --- -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 -monikerRange: '<= azure-devops' +author: ramiMSFT +ms.date: 01/09/2025 +monikerRange: '>= azure-devops-2020' --- -# Azure Artifacts overview +# What is Azure Artifacts? -[!INCLUDE [version-lt-eq-azure-devops](../includes/version-lt-eq-azure-devops.md)] +[!INCLUDE [version-gt-eq-2020](../includes/version-gt-eq-2020.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-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 -| 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 range="azure-devops-2022" -## Artifacts free tier and upgrade +# [NuGet](#tab/nugetserver22) -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/dotnetserver22) -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) + +# [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) + +--- + +::: moniker-end -1. Sign in to your Azure DevOps organization. +::: moniker range="azure-devops-2020" -1. Select ![gear icon](../media/icons/gear-icon.png) **Organization settings**. +# [NuGet](#tab/nugetserver20) - :::image type="content" source="../media/settings/open-admin-settings-vert.png" alt-text="A screenshot showing how to access the organization settings"::: +- **Quickstart:** [Get started with NuGet packages in Azure Artifacts](./get-started-nuget.md) -1. Select **Billing**. +# [dotnet](#tab/dotnetserver20) - :::image type="content" source="../organizations/billing/media/shared/select-billing-organization-settings.png" alt-text="A screenshot showing how to access the billing settings"::: +- **Quickstart:** [Publish and restore NuGet packages from the command line (dotnet)](nuget/dotnet-exe.md) -1. View your Artifacts tier and usage limit. +# [Npm](#tab/npmserver20) - :::image type="content" source="media/billing-settings.png" alt-text="A screenshot showing Artifacts tier and usage limit"::: +- **Quickstart:** [Get started with npm packages in Azure Artifacts](./get-started-npm.md) + +# [Maven](#tab/mavenserver20) + +- **Quickstart:** [Get started with Maven packages in Azure Artifacts](./get-started-maven.md) + +# [Gradle](#tab/gradleserver20) + +- **Quickstart:** [Get started with Gradle packages in Azure Artifacts](./maven/publish-with-gradle.md) + +# [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 | +|------------------------|-----------------------|--------------------------|--------------------------| +| **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"::: | +| **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"::: | +| **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"::: | +| **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"::: | +| **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"::: | +| **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"::: | +| **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"::: | +| **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 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. +::: moniker-end -> [!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. +## Increase Artifacts storage limit -### Q: I'm storing Artifacts but my storage consumption shows 0 GiB? +[!INCLUDE [](includes/increase-storage-limit.md)] -A: 1 GiB is currently our lowest granularity, so you most likely haven't reached 1 GiB yet. +## FAQs -### Q: How can I control how many days Artifacts are kept? +::: moniker range=" azure-devops" -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). +#### Q: Which artifacts contribute to my total billed storage? -### Q: How can I delete specific packages? +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. -A: See [Delete and recover packages](how-to/delete-and-recover-packages.md) for details. +> [!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: What happens if I remove my Azure Subscription from my Azure DevOps organization? -### Q: How long does it take for deleted Artifacts to reflect in the amount of billed storage? +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-artifacts-storage-limit). -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. +#### Q: Why does my storage consumption show as 0 GiB even though I'm storing Artifacts? -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. +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. -:::image type="content" source="media/settings-vs-storage.png" alt-text="Artifacts billing settings vs Artifacts storage data"::: +#### Q: How long does it typically take for the removal of Artifacts to be reflected in the billed storage amount? -### Q: What happens if I remove my Azure Subscription from my Azure DevOps organization? +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. -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. +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..af32d4d05ba 100644 --- a/docs/artifacts/symbols/debug-with-symbols-visual-studio.md +++ b/docs/artifacts/symbols/debug-with-symbols-visual-studio.md @@ -3,16 +3,15 @@ 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' +monikerRange: '>= azure-devops-2020' "recommendations": "true" --- # Debug with Visual Studio -[!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] +[!INCLUDE [version-gt-eq-2020](../../includes/version-gt-eq-2020.md)] Symbol servers enable debuggers to automatically retrieve the correct symbol files without knowing product names, build numbers or package names. These files contain useful information for the debugger and generally have the *PDB* extension. You can use Visual Studio to consume your symbols from Azure Artifacts symbol server or other external sources to step into your code and debug your application. @@ -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..4c58c742772 100644 --- a/docs/artifacts/symbols/debug-with-symbols-windbg.md +++ b/docs/artifacts/symbols/debug-with-symbols-windbg.md @@ -2,47 +2,53 @@ 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 -monikerRange: '<= azure-devops' +ms.date: 09/26/2023 +monikerRange: '>= azure-devops-2020' --- # Debug with WinDbg -[!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] +[!INCLUDE [version-gt-eq-2020](../../includes/version-gt-eq-2020.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..7fabf4531ae 100644 --- a/docs/artifacts/toc.yml +++ b/docs/artifacts/toc.yml @@ -1,237 +1,356 @@ - 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 - Maven + displayName: maven, pom, artifacts, package + href: maven/project-setup-maven.md + - name: Project setup - Gradle + displayName: Maven, Gradle + href: maven/project-setup-gradle.md + - name: Publish packages - Maven + displayName: maven, publish + href: maven/publish-packages-maven.md + - name: Publish artifacts with Gradle + displayName: gradle, publish + href: maven/publish-with-gradle.md + - 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 - href: maven/pom-and-settings.md + 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 - Maven displayName: maven pom, maven artifacts, maven packages, maven authentication - - name: Install Maven artifacts + href: maven/project-setup-maven.md + - name: Project setup - Gradle + displayName: Maven, Gradle + href: maven/project-setup-gradle.md + - name: Restore Maven packages + displayName: maven, restore, install href: maven/install.md - displayName: maven artifacts, maven packages, maven feeds - - name: Publish artifacts with Gradle - 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: 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: Restore packages from 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..418092bf819 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)] diff --git a/docs/artifacts/tutorials/powershell-upstream-source.md b/docs/artifacts/tutorials/powershell-upstream-source.md new file mode 100644 index 00000000000..7486c88bf2e --- /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-a-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..add8cbdd173 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-a-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-a-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..49e067896cd 100644 --- a/docs/artifacts/tutorials/protect-oss-packages-with-upstream-sources.md +++ b/docs/artifacts/tutorials/protect-oss-packages-with-upstream-sources.md @@ -1,178 +1,89 @@ --- -title: How to use upstream sources in your Azure Artifacts feed -description: Use upstream sources in Azure Artifacts to consume packages from public registries +title: How to restore packages from upstream sources in your Azure Artifacts feed +description: Learn how to consume packages from public registries with upstream sources in Azure Artifacts. ms.service: azure-devops-artifacts -ms.date: 06/03/2022 -monikerRange: '<= azure-devops' +ms.date: 06/24/2025 +monikerRange: '>= azure-devops-2020' +ms.custom: sfi-image-nochange "recommendations": "true" --- -# Tutorial: How to use upstream sources +# Tutorial: How to restore packages from upstream sources -[!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] +[!INCLUDE [version-gt-eq-2020](../../includes/version-gt-eq-2020.md)] -Using upstream sources in your feed enables you to manage your application dependencies from a single feed. Using upstream sources makes it easy to consume packages from public registries while having protection against outages or compromised packages. You can also publish your own packages to the same feed and manage all your dependencies in one location. +Using upstream sources in Azure Artifacts enables you to manage all your application dependencies from a single feed. It simplifies consuming packages from public registries like *NuGet.org* or *npmjs.com*, while also providing protection against outages or compromised packages. You can also publish your own packages to the same feed and manage all your dependencies in one location. -This tutorial will walk you through how to enable upstream sources on your feed and consume packages from public registries such as NuGet.org or npmjs.com. +This tutorial walks you through enabling upstream sources in your feed and consuming packages from public registries such as *NuGet.org* or *npmjs.com*. -In this tutorial, you will: +## Prerequisites ->[!div class="checklist"] -> * Create a new feed and enable upstream sources. -> * Set up your configuration file. -> * Run an initial package restore to populate your feed. -> * Check your feed to view the saved copy of the packages you consumed from the public registry. +| **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. | ## Create a feed and enable upstream sources -::: moniker range=">= azure-devops-2019" +1. Sign in to your Azure DevOps organization, and then navigate to your project. -1. Select **Artifacts**. +1. Select **Artifacts**, and then select **Create Feed** to create a new feed. - :::image type="content" source="../media/goto-feed-hub-azure-devops-newnav.png" alt-text="Screenshot showing how to navigate to Azure Artifacts."::: +1. Provide a **Name** for your feed, choose its **Visibility** and **Scope**, and make sure you check the **Include packages from common public sources** checkbox to enable upstream sources. -::: moniker-end - -::: moniker range="tfs-2018" - -1. Select **Build & Release**, and then select **Packages**. +1. Select **Create** when you're done. - :::image type="content" source="../media/goto-feed-hub.png" alt-text="Screenshot showing how to navigate to Azure Artifacts - TFS."::: - -::: moniker-end + :::image type="content" source="../media/new-feed-with-upstream-source.png" alt-text="a Screenshot displaying how to create a new feed and enable upstream sources in Azure Artifacts."::: -::: moniker range=">= azure-devops-2019" - -2. 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 +> [!IMPORTANT] +> 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** . -::: moniker range="tfs-2018" +## Authenticate with the feed -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 - - :::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 - -## Set up the configuration file - -Now that we created our feed, we need to update the config file to point to our feed. To do this we must: - -1. Get the source's URL -1. Update the configuration file +Now that you've created your feed, select the appropriate tab based on the technology you're using and follow the instructions to set up your configuration file and connect to your feed: #### [npm](#tab/npm/) -::: moniker range=">= azure-devops-2019" - -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. On the left side of the page, select the **npm** tab. - -1. Follow the instructions in the **Project setup** section to set up your config file. - - :::image type="content" source="../media/connect-to-feed-npm-registry-azure-devops-newnav.png" alt-text="Screenshot showing how to set up your project."::: - -::: moniker-end - -::: moniker range="tfs-2018" +1. Sign in to your Azure DevOps organization, and then navigate to your project. -1. Select **Build & Release** > **Packages**, and then select **Connect to Feed**. +1. Select **Artifacts**, select your feed from the dropdown menu, 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. Select **npm** from the left navigation pane, and follow the provided instructions in the **Project setup** section to set up your config file. If you don’t already have a *.npmrc* file, create a new one in the root of your project (the same folder as your *package.json*). Open your new *.npmrc* file and paste in the provided snippet. -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. + :::image type="content" source="../media/connect-to-feed-npm-registry-azure-devops-newnav.png" alt-text="A screenshot displaying how to set up your npm project in Azure Artifacts."::: #### [NuGet](#tab/nuget/) -1. Select **Artifacts**, and 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 choose **NuGet.exe**. +1. Select **Artifacts**, select your feed from the dropdown menu, and then select **Connect to feed**. - :::image type="content" source="../media/nuget-connect-to-feed.png" alt-text="Screenshot showing how to connect to NuGet feeds."::: +1. Select **NuGet.exe** from the left navigation pane, then copy the XML snippet provided in the **Project Setup** section. -1. Copy the XML snippet in the **Project Setup** section. +1. Create a new *nuget.config* file in the root of your project, and paste in the XML snippet you copied in the previous step. -1. Create a new file named *nuget.config* in the root of your project. +#### [Python](#tab/pip/) -1. Paste the XML snippet in your config file. +1. Sign in to your Azure DevOps organization, and then navigate to your project. -#### [Pip](#tab/pip/) +1. Select **Artifacts**, select your feed from the dropdown menu, and then select **Connect to feed**. -1. Select **Artifacts**, and then select your feed from the dropdown list. - -1. Select **Connect to feed**, and then select **pip** under the Python section. - - :::image type="content" source="../media/project-setup-pip.png" alt-text="A screenshot showing how to connect to a feed with pip projects."::: +1. Select **pip** from the left navigation pane. 1. Create a [virtual environment](https://go.microsoft.com/fwlink/?linkid=2103878) if you haven't done so already. -1. Add a pip.ini (Windows) or pip.conf (Mac/Linux) file to your virtualenv and paste the following snippet: - - ```command - [global] - 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. +1. Add a *pip.ini* (Windows) or *pip.conf* (Mac/Linux) file to your virtualenv and paste in the snippet provided in the **Project setup** section. #### [Maven](#tab/maven/) -1. Select **Artifacts**, and then select your feed from the dropdown list. +1. Sign in to your Azure DevOps organization, and then navigate to your project. -1. Select **Connect to feed**, and then select **Maven**. +1. Select **Artifacts**, select your feed from the dropdown menu, and then select **Connect to feed**. - :::image type="content" source="../media/project-setup-maven.png" alt-text="A screenshot showing how to connect to a feed with Maven projects."::: +1. Select **Maven** from the left navigation pane. -1. Add the following snippet to the `` and `` sections in your pom.xml: +1. Add the snippet provided in the **Project setup** section to the `` and `` sections in your *pom.xml*. Your file should look similar to the following: - ```command + ```xml [FEED-NAME] https://pkgs.dev.azure.com/[ORGANIZATION-NAME]/_packaging/[FEED-NAME]/maven/v1 @@ -185,9 +96,9 @@ If you don't have a *.npmrc* file already, create a new one in the root of your ``` -1. Add a `` to your settings.xml file: +1. Paste the provided `` snippet into your *settings.xml* file. You file should look similar to this: - ```command + ```xml ` to your settings.xml file: +1. Paste the provided `` snippet into your *settings.xml* file. Your file should resemble the following: - ```command + ```xml [!NOTE] -> The `--force` argument will force pull remotes even if a local copy exists. + ```Command + npm install --force + ``` -Your feed now should contain any packages you saved from the upstream source. +> [!NOTE] +> The `--force` flag ensures that packages are pulled from the remote source even if a local copy exists. # [NuGet](#tab/nugetrestore) -- **Clear your local cache**: +1. Clear your local cache. ```Command nuget locals -clear all ``` -- **Restore packages**: +1. Open a command prompt window and run the following command to restore your packages. Once completed, your feed should have a saved copy of any packages installed from upstream. ```Command nuget.exe restore ``` -Your feed now should contain any packages you saved from the upstream source. +# [Python](#tab/python) + +- Open a command prompt window and run the following command in your project directory to restore your packages. Once completed, your feed should have a saved copy of any packages installed from upstream. + + + ```Command + pip install + ``` + +# [Maven](#tab/mavenrestore) + +- Open a command prompt window and run the following command in your project directory to restore your packages. Once completed, your feed should have a saved copy of any packages installed from upstream. + + + ```Command + mvn install + ``` + +# [Gradle](#tab/gradlerestore) + +- Open a command prompt window and run the following command in your project directory to restore your packages. Once completed, your feed should have a saved copy of any packages installed from upstream. + + ```Command + gradle build + ``` + +# [Cargo](#tab/cargorestore) + +- Open a command prompt window and run the following command in your project directory to restore your packages. Once completed, your feed should have a saved copy of any packages installed from upstream. + + ```Command + cargo build + ``` - - - -## Related articles +::: moniker-end + +::: moniker range="azure-devops-2020" + +# [npm](#tab/npmrestoreserver) + +1. Remove the *node_modules* folder from your project. + +1. Open a command prompt window and run the following command to restore your packages. Once completed, your feed should have a saved copy of any packages installed from upstream. + + ```Command + npm install --force + ``` + +> [!NOTE] +> The `--force` flag ensures that packages are pulled from the remote source even if a local copy exists. + +# [NuGet](#tab/nugetrestoreserver) + +1. Clear your local cache. + + ```Command + nuget locals -clear all + ``` + +1. Open a command prompt window and run the following command to restore your packages. Once completed, your feed should have a saved copy of any packages installed from upstream. + + ```Command + nuget.exe restore + ``` + +# [Python](#tab/pythonrestoreserver) + +- Open a command prompt window and run the following command in your project directory to restore your packages. Once completed, your feed should have a saved copy of any packages installed from upstream. + + ```Command + pip install + ``` + +# [Maven](#tab/mavenrestoreserver) + +- Open a command prompt window and run the following command in your project directory to restore your packages. Once completed, your feed should have a saved copy of any packages installed from upstream. + + ```Command + mvn install + ``` + +# [Gradle](#tab/gradlerestoreserver) + +- Open a command prompt window and run the following command in your project directory to restore your packages. Once completed, your feed should have a saved copy of any packages installed from upstream. + + ```Command + gradle build + ``` + +- - - + +::: moniker-end + +## Related content + +- [Manage permissions](../feeds/feed-permissions.md) + +- [Publish & download pipeline artifacts](../../pipelines/artifacts/pipeline-artifacts.md) -- [Set up upstream sources](../how-to/set-up-upstream-sources.md) -- [Universal Packages upstream sources](../universal-packages/universal-packages-upstream.md) -- [Feed permissions](../feeds/feed-permissions.md) -- [Publish packages to NuGet.org](../nuget/publish-to-nuget-org.md) \ No newline at end of file +- [Publish symbols with Azure Pipelines](../../pipelines/artifacts/symbols.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..f9b1d375de8 100644 --- a/docs/boards/backlogs/add-link.md +++ b/docs/boards/backlogs/add-link.md @@ -1,392 +1,482 @@ --- -title: Link user stories and issues to other work items in Azure Boards +title: Link work items to 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, peer-review-program 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: 05/08/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 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 item** | Connects a work item to 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 remote link types, hyperlinks, attached files, parent/child, related, and predecessor-successor, see [Work link types](../queries/link-type-reference.md#work-link-type). For a list of all link types that you can specify using the Azure DevOps SLI, run the [az boards work-item relation list-type](../queries/link-type-reference.md#list-link-types) command. -::: 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 +### Manage parent/child links +You can use various features to link or modify links that use the **Parent/Child** link type. Some features depend on the version of Azure DevOps you are using. Refer to the following options for managing these links: -::: 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 +- **Organize your backlog**: [Use the mapping pane](../backlogs/organize-backlog.md) to link backlog items to portfolio backlog items or change the link structure. You can also choose **Show Parents** and [drag-and-drop items within the tree hierarchy](organize-backlog.md). +- **Sprint backlog**: [Create and link tasks to backlog items](../sprints/assign-work-sprint.md) using the sprint backlog page. You can also drag-and-drop items to adjust the link structure directly in the web portal. +- **Reparent and reorder items**: [Indent, outdent, and change the link structure](../backlogs/organize-backlog.md) of a tree hierarchy in the web portal or use a [tree query in Team Explorer](../queries/using-queries.md). +- **Excel integration**: [Add, delete, or modify work items](../backlogs/office/bulk-add-modify-work-items-excel.md) and adjust the link structure using Excel. -> [!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). +These tools provide flexibility for managing Parent/Child links based on your workflow and preferences. -For an overview of how links are used to support traceability, see [End-to-end traceability](../../cross-service/end-to-end-traceability.md). +## Link a work item to another work item -## Link guidance +#### [Browser](#tab/browser/) -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: +To add a link to another work item in the web portal, do the following steps: -- 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. +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**. -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. + :::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."::: -[!INCLUDE [temp](../includes/prerequisites.md)] +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**. - + The following example uses the **Related** link type to a test case with ID of *280*. -## Link several work items + ::: 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."::: -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. + You can only add links one at a time. You can't enter their IDs separated by commas or spaces. + ::: moniker-end -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" + 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 - Here we multi-select from the product backlog and choose **Existing item...**. +#### [Azure DevOps CLI](#tab/azure-devops-cli) - > [!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 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*, 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. -## Link to an existing work item +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. -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). +```azurecli +az boards work-item relation add --id + --relation-type + [--detect {false, true}] + [--org] + [--target-id] + [--target-url] +``` -- 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. +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/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 +``` -#### [Browser](#tab/browser/) +To view the information for the linked work items, enter one of the URLs listed in your browser. -From the **Add link** dialog, select the link type, enter a work item ID, and then choose OK. +### Show details of links made for a single work item -For example, here we use the **Related** link type to link three items to the bug with ID of *400*. +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. -::: 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) +```azurecli +az boards work-item relation show --id + [--detect {false, true}] + [--org] +``` -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. +The following command lists the details of links defined for work item *ID=2931* in the *fabrikam* organization in table format. -> [!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). +```azurecli +az boards work-item relation show --id 2931 --output table +Relation Type Url +--------------- ----------------------------------------------------------------------------------------------------------------------------------- +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 +``` -::: moniker-end +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 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) +::: moniker-end -::: 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) +[!INCLUDE [temp](../../includes/note-cli-not-supported.md)] -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 - +--- -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. +::: moniker range=">= azure-devops-2020" -::: 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 +## Link work items to pull requests -::: 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 +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. + :::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."::: -### [Visual Studio](#tab/visual-studio/) +1. To narrow the list of suggested work items, enter up to five keywords that match the work item type, ID, or title. -From the Add link to Multiple Items dialog, select the link type, enter a work item ID, and then choose **OK**. + :::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."::: -For example, here we use the **Related** link type to link several items to the user story with ID of *4654*. +::: moniker-end -![Screenshot of Visual Studio, Add link dialog.](media/add-link-related-existing-item-vs.png) +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). -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). +## Link several work items -You'll need to bulk save the work items you've modified. +1. From the web portal, open a [backlog](create-your-backlog.md) or [query results page](../queries/view-run-query.md). +2. To add a link, [multi-select (highlight) the work items](bulk-modify-work-items.md#multi-select). +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...**. -* * * + In the following example, we multi-select from the product backlog and choose **Link to an existing item...**. - + :::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."::: -::: moniker range="azure-devops" +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" ## Change the link type of an existing link -> [!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. +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**. + + :::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. Choose the link type to change to, and then select **Save**. + + :::image type="content" source="media/add-link/edit-link-dialog.png" alt-text="Screenshot of Edit link dialog."::: + +::: moniker-end + +## Link work items to new work items + +Do the following steps to link a work item to a new work item. + +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."::: + +2. Specify the **Link type** and **Work Item Type**, and enter a title for the new work item and optional comment. Select **Add link**. + + :::image type="content" source="media/add-link-related-new-item-issue.png" alt-text="Screenshot of Add link dialog, Link to new work item."::: + + The new work item opens. + +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."::: + +::: moniker range=" azure-devops" + + + +## Link work items to remote work items (cross-organization) + +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. + +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."::: + +2. Choose one of the following remote link types from the **Link type** dropdown menu: -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. + - **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. - :::image type="content" source="media/add-link/change-link-type.png" alt-text="Screenshot of Links tab, open More actions, choose Edit link option."::: +3. Enter the URL of the remote work item, and then select **Add link**. -1. Choose the link type to change to, and then choose **Save**. + 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/edit-link-dialog.png" alt-text="Screenshot of Edit link dialog. "::: + :::image type="content" source="media/add-link/add-remote-related-link.png" alt-text="Screenshot of removing a work item link."::: -1. Save the work item to complete the action. + 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 + -## 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 name 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. -::: 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. + -## More options for modifying links in bulk +## Link work items to a Web site, network share, storyboard, or document -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): +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. -- 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). +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. +:::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."::: -[!INCLUDE [temp](../includes/view-linked-objects.md)] +## View dependencies and track related work - +Azure DevOps provides several ways to view dependencies and track related work: -::: moniker range="azure-devops" +- **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. -## Add, remove, and show links using Azure CLI +To view the list of all objects linked to a work item, do the following steps: -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. 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. -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. + :::image type="content" source="../media/view-link-list/links-tab-link-count.png" alt-text="Screenshot of Links tab with count of linked objects."::: -```azurecli -az boards work-item relation add -az boards work-item relation remove -az boards work-item relation show -``` +1. (Optional) Expand or collapse each group, and sort within each group by **State**, **Latest Update**, or **Comment** by choosing the corresponding column title. -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). + 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"::: -### Link work items + 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. -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. +## Query for linked work items -#### Syntax +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**. -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. +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. -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. +You can’t query for work items in releases, but you can query for work items with external links. To refine your search, add more query filters. -```azurecli -az boards work-item relation add --id - --relation-type - [--detect {false, true}] - [--org] - [--target-id] - [--target-url] -``` +For more information, see [Query work items by link or attachment count](../queries/linking-attachments.md). -#### Example +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). -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. +## Remove work item links -```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 -``` -To view the information for the linked work items, enter one of the URLs listed in your browser. +Do the following steps to delete a work item link. -### Remove work item links +#### [Browser](#tab/browser/) + +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. + +#### [Azure DevOps CLI](#tab/azure-devops-cli) + +::: moniker range="azure-devops" 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 +486,40 @@ 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 -``` -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 - -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] +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 ``` -#### 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 -``` +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. Choose the URL for an attached file to download the attachment. - ::: moniker-end -## Related articles - -::: moniker range=">= azure-devops-2020" +[!INCLUDE [temp](../../includes/note-cli-not-supported.md)] -- [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) +--- -::: 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 content -::: 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..4982a582833 100644 --- a/docs/boards/backlogs/configure-your-backlog-view.md +++ b/docs/boards/backlogs/configure-your-backlog-view.md @@ -4,53 +4,65 @@ 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: 07/01/2025 +# customer intent: As a team member, I want to configure my backlog view options so that I can organize, prioritize, and track work items effectively for my team's workflow and project requirements. --> --- # Configure your backlog view in Azure Boards -[!INCLUDE [version-gt-eq-azure-devops-2019](../../includes/version-gt-eq-2019.md)] +[!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.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 help teams define, prioritize, and organize work hierarchically while assigning tasks to iterations and forecasting progress. Each backlog is a shared team resource where changes to items, priorities, and parent-child links are instantly visible to all team members. -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. +This article shows you how to configure your backlog view options—including backlog levels, view settings, column options, and filtering—to align with your team's workflow and project requirements. -To effectively perform select tasks, it's good to know how to set your view options to support those tasks. +## Prerequisites -> [!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). +| 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."::: +Customize your backlog view with these configuration tools: + +- **Expand/collapse one level**: Show or hide hierarchical work item relationships +- **Column options**: Select which fields display as columns +- **Backlog level selector**: Switch between product and portfolio backlogs +- **View options**: Control visibility of parents, forecasting, filters, and planning panes +- **Filter toolbar**: Find specific work items by keywords, tags, or field values + +Each backlog level (Stories, Features, Epics) maintains separate configuration settings that persist across sessions. + +:::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 +### Expand and collapse the hierarchy -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. +Backlog levels default to a **collapsed view** showing only items for that level. Use the ![expand icon](../media/icons/expand_icon.png) and ![collapse icon](../media/icons/collapse_icon.png) icons to show or hide one level of the hierarchy. These settings don't persist when you navigate to other pages. > [!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. +Your team administrator configures available backlog levels, which might include custom work item types. Each backlog automatically applies your team's **Area paths** and **Iteration paths** filters. > [!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 configuring these tools, review [Create your backlog](create-your-backlog.md) to ensure your setup supports your team's requirements. + +Use the backlog level selector (next to the :::image type="icon" source="../../media/icons/view-options-icon.png" border="false"::: **View options** icon) to switch between **Product Backlog** and **Portfolio backlog** levels. Available options vary by process model and customizations, as shown in the following table. -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** @@ -79,10 +91,9 @@ From the **Backlogs** page, you can select the product backlog or a portfolio ba :::column-end::: :::row-end::: -For information on team configuration of backlog levels, see [Select backlog navigation levels for your team](../../organizations/settings/select-backlog-navigation-levels.md). +For more information, 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. @@ -92,19 +103,13 @@ The :::image type="icon" source="../../media/icons/view-options-icon.png" border :::image type="content" source="media/configure-view-options/view-options-menu-cloud.png" alt-text="Screenshot of View options menu, Azure DevOps Services."::: :::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. - - - **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**. + - **Parents**: Show hierarchical parent-child relationships. Useful for adding children, reparenting, or viewing rollup columns. + - **Forecasting**: Show forecast tool and lines. Available only for first-level backlogs with assigned **Story points**, **Effort**, or **Size**. + - **In progress items**: Show items in *In progress* workflow states. When off, hides items in *Active*, *Committed*, or *Resolved* states. See [workflow states and state categories](../work-items/workflow-and-state-categories.md). + - **Completed child items**: Show completed child items. Turn on when reviewing rollup columns. + - **Keep hierarchy with filters**: Maintain hierarchy when filtering. + - **Mapping**: Show **Mapping** pane for drag-and-drop linking to parents. Not available at the highest backlog level. + - **Planning**: Show **Planning** pane for drag-and-drop assignment to **Iteration paths**. :::column-end::: :::row-end::: ::: moniker-end @@ -115,181 +120,182 @@ The :::image type="icon" source="../../media/icons/view-options-icon.png" border :::image type="content" source="media/configure-view-options/view-options-menu.png" alt-text="Screenshot of View options menu."::: :::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**. + - **Parents**: Show hierarchical parent-child relationships. Useful for adding children, reparenting, or viewing rollup columns. + - **Forecasting**: Show forecast tool and lines. Available only for first-level backlogs with assigned **Story points**, **Effort**, or **Size**. + - **In progress items**: Show items in *In progress* workflow states. When off, hides items in *Active*, *Committed*, or *Resolved* states. See [workflow states and state categories](../work-items/workflow-and-state-categories.md). + - **Completed child items**: Show completed child items. Turn on when reviewing rollup columns. + - **Mapping**: Show **Mapping** pane for drag-and-drop linking to parents. Not available at the highest backlog level. + - **Planning**: Show **Planning** pane for drag-and-drop assignment 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**. +Filter work items by keywords, tags, assignments, or fields configured in **Column options**. Select the :::image type="icon" source="../../media/icons/filter-icon.png" border="false"::: **Filter** icon to activate filtering. -:::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 active, filtering displays a flat list and temporarily suspends the hierarchical view, even if **Parents** is enabled. The filter toolbar stays 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. +Filter your backlog while preserving hierarchy by enabling **Parents** and **Keep hierarchy with filters** in 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 to filter by team members, work item types, paths, or keywords while maintaining the hierarchy. Matching items appear 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. +Quickly capture work items and refine details later. Use backlog queries to triage and enhance items after adding them. -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, turn **Off** **Parents** and **Forecasting** to simplify the view. + +3. (Optional) Configure more settings: + - **In progress items**: Show or hide items currently in progress. + - **Column display**: Minimize columns or select specific fields, streamlining 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 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. +Prioritize your backlog to ensure the most important work items are addressed first: -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 (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 **Off** the **Parents** option to simplify the view. - 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 to adjust priority. + - **Keyboard shortcuts**: Hold **Alt** and use arrow keys to move 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] +> Priority changes affect all team members and update automatically when they refresh their backlogs. 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 relative ranking and are assigned separately for each backlog level. By default, these fields don't appear on work item forms. + +Some backlogs might restrict reordering due to portfolio management or nested items. For more information, see: +- [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. - +Portfolio backlog prioritization works like product backlog prioritization, except you prioritize child items within each portfolio item. Each backlog level (**Stories**, **Features**, **Epics**) supports separate priority ordering. -**Prioritize the portfolio items:** +**Prioritize portfolio items:** 1. Select the portfolio backlog level you want to prioritize. -1. Turn the **Parents** view option **Off**. -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. +1. Turn **Off** the **Parents** view option. +1. Drag work items up or down within the backlog. **Prioritize child items:** 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) +Quickly link work items to parent portfolio items 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, add and prioritize the portfolio backlog items you want to link to. The **Mapping** pane lists portfolio items in priority order. + +1. Choose the backlog level where you want to link work items (for example, **Stories** to **Features**). -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. +2. Select :::image type="icon" source="../../media/icons/view-options-icon.png" border="false"::: **View options**. +3. Select **Mapping** to open the Mapping pane. The pane lists next-level portfolio items for the current team. - 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. +4. (Optional) To map items to parents owned by a different team, select the 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."::: -1. (Optional) You can also drag a backlog item within the expanded hierarchical view to reparent a work item. +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 and the backlog item's text turns bold briefly. + + To select multiple work items: + - **Sequential selection**: Hold **Shift** to select a range of items. + - **Non-sequential selection**: Hold **Ctrl** to select individual items. + - Drag the selected items to create links. + +6. (Optional) Within an expanded hierarchical view, 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 unparented work items, add the **Parent** field as a column. The parent item's **Title** appears for linked work items. ::: 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. In the work item form that appears, enter a **Title** and any other required fields or details. Save the work item to close it. +1. Select the portfolio backlog level (**Features**, for example) where you want to add items. +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. Labels might differ based on your process and customizations. +2. In the work item form, enter a **Title** and any required fields. Save the work item. 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 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. +Use the **Planning** pane to assign 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** you want to show in the **Planning** pane are selected for your team. 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. 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. Open **View options**, turn **Off** **Completed child items** and choose **Planning**. +1. Drag work items from the backlog to the desired sprint in the **Planning** pane. + The system creates assignments in the background. The backlog item turns bold briefly as the system saves 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. + To select multiple items: hold **Shift** for sequential items or **Ctrl** for individual items, then 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: -1. Make sure that future **Iteration Paths** have been selected for your team. +1. Ensure 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 your process. +4. Open **View options** and turn **Off** **Parents**, **In progress** items, and **Completed child items**. Turn **On** **Forecast**. +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 iteration assignments made to 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,35 +304,16 @@ For more information, see [Forecast your product backlog](../sprints/forecast.md ::: moniker range="azure-devops" -## Review progress made to your backlog - -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. - -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. - - :::image type="content" source="media/configure-view-options/progress-feature.png" alt-text="Screenshot of Scenario backlog showing Rollup column for Progress by Feature."::: +## Next step - 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). - +> [!div class="nextstepaction"] +> [Add rollup columns](display-rollup.md) ::: moniker-end - -## Related articles +## Related content -- [Set up your project's backlogs and boards](set-up-your-backlog.md) -- [Create your product backlog](create-your-backlog.md) +- [Create and manage 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) -- [Configure team settings](../../organizations/settings/manage-teams.md) - -### Bulk modify tools - -- [Bulk modify (web)](bulk-modify-work-items.md) -- [Bulk add or modify (Excel)](office/bulk-add-modify-work-items-excel.md) -- [Import or update work items in bulk by using CSV files](../queries/import-work-items-from-csv.md) - +- [Configure team settings](../../organizations/settings/manage-teams.md) 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..d9a9af14973 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. ::: 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/move-change-delete/move-work-item-dialog.png b/docs/boards/backlogs/media/move-change-delete/move-work-item-dialog.png index 9eda44735e6..9dac7a4339f 100644 Binary files a/docs/boards/backlogs/media/move-change-delete/move-work-item-dialog.png and b/docs/boards/backlogs/media/move-change-delete/move-work-item-dialog.png differ diff --git a/docs/boards/backlogs/media/move-to-team-project.png b/docs/boards/backlogs/media/move-to-team-project.png new file mode 100644 index 00000000000..97b28b08f52 Binary files /dev/null and b/docs/boards/backlogs/media/move-to-team-project.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..14c22dc70ca 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..c386db22c47 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: 05/05/2025 --- # 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, delete, or restore work items when the work item types support test management or belong to the [Hidden Types Category](../work-items/agile-glossary.md#hidden-types). This restriction 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. @@ -102,59 +87,60 @@ You can change a single work item or several [multi-selected work items](bulk-mo > ![Backlog, multi-select, open actions menu, choose Change type option](media/move-change-delete/change-type-new-nav.png) > [!IMPORTANT] - > From the **Query Results page**, the **Change type…** option becomes unavailable if you have checked the Query Editor's **Query across projects** checkbox. + > From the **Query Results page**, the **Change type…** option becomes unavailable if you checked the Query Editor's **Query across projects** checkbox. 2. Select the type and optionally enter a comment. ![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. + > The system automatically resets the **State** and **Reason** fields to the default initial values of the specified type. However, in some cases you might 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 can't be restored, and all associated child items, such as test results, are also removed. Additionally, bulk deletion of test artifacts isn't supported; attempting to bulk delete results 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. +1. Sign in to your organization (`https://dev.azure.com/{Your_Organization}`). +2. Select **Boards** > **Work items** :::image type="icon" source="../../media/icons/more-actions.png" border="false"::: **More actions** > **Move to team project**. - 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). + :::image type="content" source="media/move-to-team-project.png" alt-text="Screenshot shows sequence of button selections for move work item to team project."::: + + 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. Choose the :::image type="icon" source="../media/icons/actions-icon.png" border="false"::: actions icon to open the context menu of one of the selected work items, and choose the ![Move work item icon](../media/icons/change-team-project-icon.png) **Move…** option. -2. Select the destination project and choose the other options available, including changing the work item type. Optionally enter a comment. +3. Select the destination project and choose the other options available, including changing the work item type. Optionally enter a comment. ::: 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..cf7a9406e98 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) - +- [Create and manage your backlog](create-your-backlog.md) +- [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 deleted file mode 100644 index add8bf61d75..00000000000 --- a/docs/boards/backlogs/set-up-your-backlog.md +++ /dev/null @@ -1,365 +0,0 @@ ---- -title: Manage your project's backlogs and boards in Azure Boards -titleSuffix: Azure Boards -description: Learn how to configure your project's backlogs and boards. Also, learn to display user stories, issues, tasks, or other work items that your team wants to track. -ms.custom: boards-backlogs -ms.service: azure-devops-boards -ms.assetid: -ms.author: chcomley -author: chcomley -ms.topic: how-to -monikerRange: '<= azure-devops' -ms.date: 04/01/2022 ---- - -# Set up your project's backlogs and boards in Azure Boards - -[!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). - -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. - -For an overview of the tools associated with your team, see [Manage and configure team tools](../../organizations/settings/manage-teams.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" - -- 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 - - [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 - -[!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" - -> [!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). - - - -## 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). - -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: - -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). - -2. [Create a query](../queries/using-queries.md) of your backlog items, specifying the work item types that belong to your Requirements category and the Area Path associated with your team, for example: - - > [!div class="mx-imgBorder"] - > ![Requirement category query](media/setup-backlog/requirements-query.png) - -3. Add the State, Area Path, and Iteration Path fields to the [column options](set-column-options.md). - -4. Check the query results and that the values of the work items you expect to show up on your backlog meet these criteria: - - Area Path belongs to your team's area path(s) - - Iteration Path belongs under your team's default iteration path - - State isn't Closed, Completed, Done, or Removed. - -> [!NOTE] -> You can also filter your product backlog to show or hide work items that are in an **In Progress** state category, corresponding to an Active, Resolved, Committed, Doing workflow state. - -## Add bugs to your backlogs and boards - -::: moniker range=">= azure-devops-2019" - -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. - -::: 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"] -> ![Working with bugs options](media/setup-backlog/working-with-bugs.png) - -For more information, see [Show bugs on backlogs and boards](../../organizations/settings/show-bugs-on-backlog.md). - -## Correct your Kanban 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. - -> [!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). - - -## Customize your Kanban 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). - -::: moniker range=">= azure-devops-2019" - -For example, here we've chosen to track bugs along with tasks, and enable Task, Bug, GitHub objects, and Tests to appear within checklists. - -> [!div class="mx-imgBorder"] -> ![On the settings page, the Annotations tab is selected and four Annotation types, all enabled, are listed. They are: Task, Bug, GitHub, and Tests.](../boards/media/customize-cards/annotate-settings-154.png) - -::: moniker-end - -::: moniker range="azure-devops-2019" -> [!NOTE] -> The GitHub annotations require Azure DevOps Server 2019 update 1 or later version. - -::: moniker-end - -::: moniker range=">= azure-devops-2019" - -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) -- [Link GitHub commits, pull requests, and issues to work items](../github/link-to-from-github.md) - -::: moniker-end - - -::: moniker range="tfs-2018" - - -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). - -> [!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. - -> [!div class="mx-imgBorder"] -> ![Backlog navigation levels](media/setup-backlog/backlog-levels.png) - -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 - -If you want to track different work item types on your product backlog, you can do that by adding custom work item types and adding them to a specific backlog level. - -You can also add custom work item types and add them to portfolio backlogs. You can add up to five portfolio backlogs. - -For example, here we've added Initiatives, fourth level, and fifth level work item types to support five levels of portfolio backlogs. We've also added a custom work item type named Ticket and added that to the product backlog. - -> [!div class="mx-imgBorder"] -> ![Add custom work item types to your backlogs.](media/setup-backlog/backlog-levels-customized.png) - -For more information, see the following resources: - -::: moniker range="azure-devops" - -- [Add and manage work item types (Inherited process)](../../organizations/settings/work/customize-process-work-item-type.md) -- [Customize your backlogs or boards (Inherited process)](../../organizations/settings/work/customize-process-backlogs-boards.md) -- [Customize an inheritance process](../../organizations/settings/work/inheritance-process-model.md) - -::: moniker-end - -::: moniker range=">= azure-devops-2019 < azure-devops" - -**Inheritance process model:** -- [Add and manage work item types (Inherited process)](../../organizations/settings/work/customize-process-work-item-type.md) -- [Customize your backlogs or boards (Inherited process)](../../organizations/settings/work/customize-process-backlogs-boards.md) -- [Customize an inheritance process](../../organizations/settings/work/inheritance-process-model.md) - -**On-premises XML process model:** -- [Add a work item type to a backlog and board](../../reference/add-wits-to-backlogs-and-boards.md) -- [Add portfolio backlogs](../../reference/add-portfolio-backlogs.md) -- [Customize the On-premises XML process model](../../reference/on-premises-xml-process-model.md) - -::: moniker-end - -::: moniker range="tfs-2018" - -- [Add a work item type to a backlog and board](../../reference/add-wits-to-backlogs-and-boards.md) -- [Add portfolio backlogs](../../reference/add-portfolio-backlogs.md) -- [Customize the On-premises XML process model](../../reference/on-premises-xml-process-model.md) -- [Add portfolio backlogs](../../reference/add-portfolio-backlogs.md) - -::: moniker-end - - - -## 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 " -> [!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. - -::: moniker-end - -::: moniker range=">= azure-devops-2019" - -### Track custom work items with the Inherited process model - -For example, if you want to track a custom work item type, Tickets, along with Tasks and Bugs, you do the following tasks: - -1. Define the Ticket custom work item type. See [Add and manage work item types](../../organizations/settings/work/customize-process-work-item-type.md). - -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 - -For on-premises deployments that use the On-premises XML process model to customize work tracking, you can add existing and custom work item types to the sprint Taskboards. For example, if you want to track Issues (or Impediments for the Scrum process) and a custom work item type, Tickets, along with Tasks and Bugs, you would do the following tasks: - -1. Define the Ticket custom work item type. See [Add or modify a work item type](../../reference/add-modify-wit.md). -2. Add Issue and Ticket work item types to the Task Category by modifying the Categories XML file. For more information, see [Categories XML element reference](/previous-versions/azure/devops/reference/xml/categories-xml-element-reference). - - For example, here we add Issue and Ticket to the Task Category. - - > [!div class="tabbedCodeSnippets"] - > ```XML - > - > - > - > ``` - -3. Make sure that the Issue and Ticket workflow states are mapped to category states. As needed, modify the ProcessConfiguration XML file to add Issues and Tickets to the `TaskBacklog` section. - - For example, here the New, Active, and Closed states are mapped for the Task Category. - - > [!div class="tabbedCodeSnippets"] - > ```XML - > - > - > - > - > - > - > . . . - > - > ``` - -4. To verify your changes, open a Sprint backlog and make sure you can add an Issue or Ticket in the same way you add a Task. See [Add tasks](../sprints/add-tasks.md). - -::: moniker-end - -## 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. - - > [!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've turned off the **In Progress** view, then those work items where work has started won't appear in the backlog list. - - ::: moniker range=">= azure-devops-2020" - > [!div class="mx-imgBorder"] - > ![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). - -- 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. - -- Sprint backlogs show only those work items that meet the team's area path and the **Iteration Path** defined for the sprint. - -- Inheritance process model: If an administrator [disables or deletes a work item type](../../organizations/settings/work/customize-process-work-item-type.md#enable-disable), it doesn't appear on backlogs and boards. - -- 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) diff --git a/docs/boards/backlogs/toc.yml b/docs/boards/backlogs/toc.yml index ea42f637fe5..967299cc8d8 100644 --- a/docs/boards/backlogs/toc.yml +++ b/docs/boards/backlogs/toc.yml @@ -21,11 +21,8 @@ - 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: 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: Automate work item state transitions + href: automate-work-item-state-transitions.md - name: Change column options href: set-column-options.md - name: Display rollup progress bars or totals @@ -37,9 +34,6 @@ href: ../../organizations/settings/show-bugs-on-backlog.md?bc=%252fazure%252fdevops%252fboards%252fbreadcrumb%252ftoc.json&toc=%252fazure%252fdevops%252fboards%252ftoc.json - name: Best practices, monitoring, & reports items: - - name: Refine your backlog - href: best-practices-product-backlog.md - displayname: product owner, role, acceptance criteria, spikes - name: Rollup of work & other fields href: ../../reference/xml/support-rollup-of-work-and-other-fields.md?toc=/azure/devops/boards/toc.json displayname: native, Planning pane, tools, query charts, Excel 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..5af335f29c2 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,26 @@ 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 + The setting you choose applies to all active boards for your team. -::: 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 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..6ca9b12bfed 100644 --- a/docs/boards/boards/expedite-work.md +++ b/docs/boards/boards/expedite-work.md @@ -2,160 +2,138 @@ 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: 07/02/2025 --- # 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. +> - When you have many swimlanes or cards on your board, you might encounter slow performance when dragging a card. We recommend that you use swimlanes with card styles, tags, and board filters to manage your work items. If you have numerous 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 + +::: moniker range="azure-devops" ## 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 +158,35 @@ 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."::: +::: moniker-end + ## 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 +202,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..59c5113420e 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) -- [Set up your Backlogs and Boards](backlogs/set-up-your-backlog.md) +- [Configuration and Customization FAQs](../organizations/settings/work/faqs.yml) +- [Set up your backlog](backlogs/create-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..1155e74ea6d 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" @@ -48,12 +46,13 @@ sections: You can restrict access by setting permissions for an area path. For more information, see the following articles: - [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). - - name: Backlogs and Boards + - 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 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..80163502eaf 100644 --- a/docs/boards/get-started/sign-up-invite-teammates.md +++ b/docs/boards/get-started/sign-up-invite-teammates.md @@ -2,13 +2,15 @@ title: Sign up for Azure Boards titleSuffix: Azure Boards description: Learn how to sign up for free for Azure Boards. -ms.custom: boards-get-started ms.subservice: azure-devops-new-user ms.topic: quickstart ms.author: chcomley author: chcomley monikerRange: 'azure-devops' -ms.date: 03/22/2023 +ms.date: 03/13/2025 +ms.custom: + - boards-get-started + - sfi-image-nochange --- # Sign up for Azure Boards @@ -21,36 +23,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 +116,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 +126,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 +158,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 +166,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 +181,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 +193,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 +209,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 +239,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 +265,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..f5273521300 100644 --- a/docs/boards/github/connect-on-premises-to-github.md +++ b/docs/boards/github/connect-on-premises-to-github.md @@ -6,8 +6,9 @@ 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: " -::: moniker range="azure-devops-2020" When you connect your Azure DevOps Server project to your GitHub repositories, you support 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. > [!NOTE] -> On-premises Azure DevOps Server 2020 supports integration with GitHub.com and 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 - -::: moniker range="azure-devops-2019" -When you connect your Azure DevOps Server project with your GitHub Enterprise Server repositories, you support linking between GitHub commits and pull requests to work items. You can use GitHub Enterprise for software development while using Azure Boards to plan and track your work. - -> [!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 +> Azure DevOps Server supports integration with GitHub.com and GitHub Enterprise Server repositories. To connect from Azure DevOps Services, see [Connect Azure Boards to GitHub](./connect-to-github.md?preserve-view=true&view=azure-devops). ## 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 -The following authentication options are supported. +The following authentication options are supported: -::: moniker range="azure-devops-2020" -- [PAT](#server-github-ent-pat) -- [Username plus password](#server-github-ent-username) +- [GitHub PAT](#server-github-ent-pat) +- [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 -::: moniker range="azure-devops-2020" You can connect up to 250 GitHub repositories to an Azure Boards project. +::: moniker range="azure-devops-2020" > [!NOTE] -> Connection to more than 100 GitHub repositories requires Azure DevOps Server 2020.1 update or later version. -> 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. - +> - Connection to more than 100 GitHub repositories requires Azure DevOps Server 2020.1 update or later version. +> - Connection to GitHub.com repositories requires Azure DevOps Server 2020.1.1 Patch 2 or later version. ::: moniker-end 1. Open the web portal for your Azure DevOps Server. 2. Select the :::image type="icon" source="../../media/icons/project-icon.png" border="false"::: Azure DevOps logo to open **Projects**, and then choose the Azure Boards project you want to configure to connect to your GitHub Enterprise repositories. -::: moniker range="azure-devops-2020" - 3. Select **Project settings** > **GitHub connections**. - :::image type="content" source="media/github-ent/open-project-settings-github-connections-2020-1.png" alt-text="Screenshot of open Project Settings>GitHub connections."::: + :::image type="content" source="media/github-ent/open-project-settings-github-connections-2020-1.png" alt-text="Screenshot of open Project Settings, GitHub connections."::: -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: +4. If it's your 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 Personal Access Token**: For details, see [Connect using a GitHub PAT](#github-ent-pat). + - **GitHub credentials**: For details, 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 Azure DevOps Server with a GitHub Personal Access Token -#### Connect with a Personal Access Token - -1. To create a PAT, see [Creating a personal access token](https://help.github.com/en/articles/creating-a-personal-access-token-for-the-command-line). +1. To create a GitHub PAT, see [Create a GitHub PAT](https://help.github.com/en/articles/creating-a-personal-access-token-for-the-command-line). > [!TIP] > When you create your GitHub PAT, make sure that you include these scopes: `repo, admin:repo_hook, read:user, user:email`. 1. Enter the URL for your GitHub Enterprise server and the **Personal access token** credentials recognized by that server. And then select **Connect**. - :::image type="content" source="media/github-ent/ads-add-ghe-pat.png" alt-text="Screenshot of sign in with PAT."::: + :::image type="content" source="media/github-ent/ads-add-ghe-pat.png" alt-text="Screenshot of sign in with GitHub PAT."::: - + -#### Connect with a Username and Password +## Connect Azure DevOps Server 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. - :::image type="content" source="media/github-ent/ads-add-ghe-repositories.png" alt-text="Screenshot of repositories to select to add."::: + :::image type="content" source="media/github-ent/ads-add-ghe-repositories.png" alt-text="Screenshot of repositories to select to add."::: 3. To connect to a GitHub account or organization from Azure Boards for the first time, you also install the Azure Boards app for GitHub. Complete the integration by following the procedures outlined in [Confirm the connection](connect-to-github.md#confirm-connection). @@ -212,7 +104,7 @@ Choose the configuration that you set up in [Step 4 of Register your OAuth confi 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). - + 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. :::image type="content" source="media/troubleshoot/failed-connection.png" alt-text="Screenshot of failed connection."::: - -::: 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: - **If the connection is using OAuth**: - - The Azure Boards application had its access denied for one of the repositories. + - The Azure Boards application had access denied for one of the repositories. - GitHub might be unavailable/unreachable. This unavailability could be because of an outage in either service or an infrastructure/network issue on-premises. You can check service status from the following links: - [GitHub](https://status.github.com) - [Azure DevOps](https://status.dev.azure.com/) 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. +- **If the connection is using a GitHub PAT:** + - The GitHub 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 GitHub PAT and ensure the scope for the token includes the required permissions: `repo, read:user, user:email, admin:repo_hook`. - + #### 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 +236,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..7a4669302e3 100644 --- a/docs/boards/github/connect-to-github.md +++ b/docs/boards/github/connect-to-github.md @@ -1,13 +1,14 @@ --- 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 +ms.custom: sfi-image-nochange --- # Connect Azure Boards to GitHub (cloud) @@ -21,9 +22,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 +41,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 +111,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 +119,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 +137,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 +163,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 +182,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 +198,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 +227,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 +235,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 +254,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 +284,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 +296,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 +309,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 +345,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 +390,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 +416,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 +444,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..8d72560fc78 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: 06/24/2025 --- -# 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,67 +33,96 @@ 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 `{state}` or `{state category}`, along with `fix`, `fixes`, `fixed`, and applies it to the #-mention item that follows. -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). +When a pull request description includes a valid state name, for example, ``Closed AB#1234``, the system updates the referenced work item to that specific state. If the state name isn’t recognized directly, Azure Boards tries to match it to a workflow category like ``Resolved`` or ``Completed``. If a match is found, the work item transitions to the first available state defined under that category. -See the following table of examples. +By default, work items referenced with ``fix``, ``fixes``, or ``fixed`` transitions to the first state associated with the **Resolved** category. If no such state exists in the current process, the system instead transitions the work item to the first state in the **Completed** category. + +> [!IMPORTANT] +> You can still link work items and target other branches, but state transition rules don't apply unless the pull request is merged into the default branch. + +For more information, see [How workflow category states are used in Azure Boards backlogs and boards](../work-items/workflow-and-state-categories.md). + +Review the following table of examples: | Commit or pull request message | Action | | :------------------------------------------ | :----------------------------------------------- | | `Fixed AB#123` | Links and transitions the work item to the *Resolved* workflow state category or, if none is defined, then the *Completed* workflow state category. | +| `Closed AB#123` | Links and transitions the work item to the *Closed* workflow state. If none is defined, no transitions are made. | `Adds a new feature, fixes AB#123.` | Links and transitions the work item to the *Resolved* workflow state category or, if none is defined, then the *Completed* workflow state category. | | `Fixes AB#123, AB#124, and AB#126` | Links to Azure Boards work items 123, 124, and 126. Transitions only the first item, 123 to the *Resolved* workflow state category or, if none is defined, then the *Completed* workflow state category.| | `Fixes AB#123, Fixes AB#124, Fixes AB#125` | Links to Azure Boards work items 123, 124, and 126. Transitions all items to either the *Resolved* workflow state category or, if none is defined, then the *Completed* workflow state category. | | `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**. -::: moniker range=">= azure-devops-2019" + :::image type="content" source="media/link/create-github-branch-dialog.png" alt-text="Screenshot of Create a GitHub Branch dialog."::: -1. To link to a commit or pull request, open the work item and choose **Add link** under the Development section. + 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). - > [!div class="mx-imgBorder"] - > ![Screenshot of work item form, Development section, Add link option.](media/link/add-link-development-github.png) + - To link to an issue, choose the **Links** tab, and then choose **Add Link>Existing item**. +## Add work item link to GitHub branch, commit, or pull request - :::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."::: +1. Open the work item and go to the **Links** tab. -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. + :::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/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."::: +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**. - 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. + 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."::: + + 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 +131,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). + -:::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."::: +## View GitHub objects on a board -::: moniker range="azure-devops-2019" +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). -> [!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 +146,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..81da7c39d74 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: 04/29/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 Path** values or reconfiguring **Iteration Path** values causes irreversible data loss in the following charts: +> - 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** values as defined at the time for each work item +> - When you delete these paths, you can't retrieve their historical data. +> - You can delete area and iteration paths only when they're 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..2640a40990b 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 [Create your backlog](../backlogs/create-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..59cc8662eca 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 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,10 +158,8 @@ 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 - text: FAQs url: faqs.yml - title: Quick reference @@ -172,8 +172,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..6ef40deb20d 100644 --- a/docs/boards/integrations/boards-slack.md +++ b/docs/boards/integrations/boards-slack.md @@ -5,12 +5,14 @@ description: Learn how to create work items and monitor work item activity in an ms.service: azure-devops ms.subservice: azure-devops-integration ms.topic: how-to -ms.custom: cross-service ms.reviewer: karrg ms.author: chcomley author: chcomley monikerRange: 'azure-devops' ms.date: 10/20/2021 +ms.custom: + - cross-service + - sfi-image-nochange --- # Use the Azure Boards app with Slack to manage work items @@ -25,43 +27,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 +86,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 +102,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 +147,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 +197,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 +208,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..7bb59b2142a 100644 --- a/docs/boards/integrations/boards-teams.md +++ b/docs/boards/integrations/boards-teams.md @@ -1,377 +1,231 @@ --- -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 ms.subservice: azure-devops-integration -ms.custom: cross-service ms.topic: how-to ms.reviewer: karrg ms.author: karrg author: chcomley monikerRange: 'azure-devops' -ms.date: 10/26/2022 +ms.date: 08/13/2024 +ms.custom: + - cross-service + - sfi-image-nochange --- -# 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. - - ``` - @azure boards addAreapath [area path] - ``` +| 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). | - For example: +## Add the Azure Boards app to Teams - ``` - @azure boards addAreapath myproject\fabrikam - ``` +To add the Azure Boards app to your Teams channels, do the following steps. - ![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. +1. In Microsoft Teams, select **Apps**, search for *Azure Boards*, and then select **Azure Boards**. -## Create a work item with a command + :::image type="content" source="media/integrations-teams/notifications.png" alt-text="Screenshot of selecting Apps, then Azure Boards."::: -With the Azure Boards app, you can create work items from your channel. The app supports custom work items as well. +1. Select the dropdown arrow next to **Open**, and select **Add to a team**. -- To create a work item, use `@azure boards create`. + :::image type="content" source="media/integrations-teams/signin1.png" alt-text="Screenshot of selecting Open and then Add to a team."::: - ![Create work item using command](./media/integrations-teams/create-work-item-command.png) +1. Select or enter your team name, and then select **Set up a bot**. + :::image type="content" source="media/integrations-teams/signin2.png" alt-text="Screenshot of selecting Set up a bot."::: -## Create a work item from message actions +After the app installs, you see a welcome message in the Teams 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. +:::image type="content" source="media/integrations-teams/welcome-message.png" alt-text="Screenshot of the Welcome message in the conversation pane."::: -- To create work items using message actions +### Azure Boards app commands - > [!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) +You can use the following `@azure boards` commands to interact with the Azure Boards app in your Teams 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. | -## 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. - -## 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 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..ddb384e77e6 100644 --- a/docs/boards/plans/configure-hierarchical-teams.md +++ b/docs/boards/plans/configure-hierarchical-teams.md @@ -8,46 +8,49 @@ author: chcomley ms.topic: tutorial monikerRange: '<= azure-devops' ms.date: 04/01/2022 +ms.custom: sfi-image-nochange --- # Configure a hierarchy of teams [!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 +59,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 +68,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 +131,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 +175,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..b528ad33444 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: 05/06/2025 --- -# 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 but 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,132 @@ 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) -With the **Query across projects** checked, you can add the **Team Project** field to filter to a select number of projects. +::: 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 + +::: 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."::: -![Screenshot of Query Editor with Team Project and other fields added to filter.](media/using-queries/portal-query-across-two-projects.png) +::: moniker-end + +> [!NOTE] +> - Separate multiple project names using the list separator defined by the regional settings of your client computer, such as a comma `,`. +> - When you use the 'State' field in a query across multiple projects, the displayed values are limited to items defined in the default project. If you're querying across projects, you might not see all possible state values from each project, but only values from the default project. +> For example, if you have three projects—Project A, Project B, and Project C—and only Project A has a state that is called 'In Review,' while Projects B and C have different states, the query only displays the states defined in Project A. -> [!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 create queries across multiple projects, the availability of fields in the **Field** drop-down menu depends on whether the **Query across projects** option is enabled. Keep the following key behaviors in mind: -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. +- The **Team Project** field becomes 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 fields from work item types defined in the current project appear in the **Field** drop-down menu. + +With the **Query across projects** checked, you can add the **Team Project** field to filter to a select number of projects. + +::: 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 + +::: moniker range="< azure-devops" + +:::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."::: + +::: 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&tabs=visual-studio&preserve-view=true#view-work-items) instead of this legacy view, which 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 +227,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, which 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 +267,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 +285,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 +292,28 @@ 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" - -> [!div class="mx-imgBorder"] -> ![Screenshot of Query Results List showing a Tree Query.](media/view-run-queries/tree-query-new-exp.png) - -::: moniker-end - -::: moniker range="tfs-2018" +::: moniker range="<=azure-devops" -> [!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) +:::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 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, which 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 +321,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, which 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 +378,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"::: ungrouped 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. - +## Set default column width in query results -#### [Visual Studio](#tab/visual-studio/) +To set the default column width in query results, do the following steps: -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. +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 +420,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. +To view the results of a query with the **Parent** title displayed, do the following steps: +1. Create a 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. While the **Parent** field can be included, the default behavior might only show the ID of the parent work item. To ensure that the name displays alongside the ID, combine the **Work Item Type** and **Parent** fields with the **Title** field in the query structure. 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. +4. 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 +438,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 2,000 and 2,083 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 32-K 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,35 +168,45 @@ 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 - [Assign backlog items to a sprint](assign-work-sprint.md) -- [Setup your Backlogs & Boards](../backlogs/set-up-your-backlog.md) +- [Create and manage your backlog](../backlogs/create-your-backlog.md) - [Define iteration (sprint) paths and configure team iterations](../../organizations/settings/set-iteration-paths-sprints.md) - [Interactively filter backlogs, boards, queries, and plans](../backlogs/filter-backlogs-boards-plans.md) 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..80a31b0750c 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). @@ -225,4 +162,4 @@ Now that you've defined your sprint plan, your team's ready to begin work on the To add or rename the sprints your team uses, see [Define iteration (sprint) paths and configure team iterations](../../organizations/settings/set-iteration-paths-sprints.md). -If your backlog doesn't show the work items you expect, see [Setup your Backlogs & Boards](../backlogs/set-up-your-backlog.md). +If your backlog doesn't show the work items you expect, see [Create and manage your backlog](../backlogs/create-your-backlog.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..bd0b449131e 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) +- [Create your backlog](../backlogs/create-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..b977e538697 100644 --- a/docs/boards/sprints/end-sprint-activities.md +++ b/docs/boards/sprints/end-sprint-activities.md @@ -4,35 +4,31 @@ titleSuffix: Azure Boards description: Learn about tasks to perform to close a sprint when using Scrum in Azure Boards. ms.custom: boards-sprints, engagement-fy23 ms.service: azure-devops-boards +ai-usage: ai-assisted ms.author: chcomley author: chcomley ms.topic: how-to monikerRange: '<= azure-devops' -ms.date: 01/23/2023 +ms.date: 05/06/2025 --- # End-of-sprint activities -[!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)] - +At the end of a sprint, teams should complete several tasks to maintain backlog hygiene and ensure accurate metrics. Incomplete work shouldn't remain assigned to a past sprint, and teams must decide how to handle unfinished items. While there's no automatic way to move incomplete work items to another sprint or reset **Remaining Work** to zero, teams can take specific actions to address these issues. -At the end of a sprint, teams may want to attend to several tasks to maintain backlog hygiene. In general, incomplete work should never be assigned to a past sprint. Teams need to determine how they want to handle work that isn't completed in a sprint and take appropriate action. +Key actions to take include: +- Decide how to handle partially completed user stories and tasks at the end of the sprint. +- Manage incomplete work to ensure sprint metrics and velocity remain accurate. +- Review items in a prioritized order to maintain focus and efficiency. -> [!NOTE] -> There is no automatic way to move incomplete work items assigned to one sprint to another. Nor, an automatic method for zeroing out **Remaining Work**. - -At the end of each sprint, each team should determine and take action to address the following questions: -- *How should we address user stories and their tasks that are only partially completed at the end of the sprint?* -- *What is the correct way to manage partially done work at the end so that sprint metrics and velocity are correctly accounted for?* -- *What should we review and in what order?* - -In general, end-of-sprint activities should be done before or after a [sprint review meeting](best-practices-scrum.md#sprint-review-meetings) and before a [sprint retrospective](best-practices-scrum.md#sprint-retrospective-meetings). The main item to consider is to maintain views and metrics to support the team in their sprint reviews, retrospectives, and sprint planning. +Perform end-of-sprint activities before or after a [sprint review meeting](best-practices-scrum.md#sprint-review-meetings) and before a [sprint retrospective](best-practices-scrum.md#sprint-retrospective-meetings). These activities help maintain accurate views and metrics to support sprint reviews, retrospectives, and future sprint planning. ## Goals for end-of-sprint activities -Each sprint represents a time-boxed period of development to which work is assigned. Review the following checklist for the goals to keep in mind when performing end-of-sprint activities. +Each sprint represents a time-boxed period of development to which work is assigned. Review the following checklist for the goals to keep in mind when you perform end-of-sprint activities. - Maintain backlog hygiene where no incompleted work is assigned to a sprint whose end date is in the past - Manage work item states and sprint assignments to support monitoring of team progress and velocity @@ -40,9 +36,8 @@ Each sprint represents a time-boxed period of development to which work is assig - Support team's focus on shipping software and meeting sprint goals - Minimize work tracking efforts that have no value -> [!TIP] -> Team velocity is not a measure of team productivity and should only be used as a metric for planning future sprints. Work is either complete at the end of a sprint or it isn't. If it's done it counts. If it's not, then it gets reconsidered for a future sprint and not the current sprint. Velocity tends to level itself out no matter what choices you make. However, by considering only done work, you work toward a more realistic value and a much better source of historical data to make future forecasts. - +> [!TIP] +> Team velocity measures planning accuracy, not productivity. Only completed work counts toward velocity. Incomplete work should be reconsidered for a future sprint. By focusing on completed work, you achieve more realistic metrics and better historical data for future planning. ## Decide team preferences @@ -56,39 +51,40 @@ The following suggestions walk through the main end-of-sprint activities teams s - Split the story into two to represent the work completed in the current sprint and work yet to do. For more information, see [Copy or clone stories, issues and other work items](../backlogs/copy-clone-work-items.md). - Reassign the story to the next sprint where work can be completed. All unfinished stories in the current sprint account for zero to the sprint's velocity. -- **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. - +- **Determine how to handle Remaining Work for completed tasks.** If tasks are complete, then having a nonzero value for **Remaining Work** doesn't make much 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 -To determine incomplete work, review the Sprint backlog for work that is still in a committed, active, in progress state. +To determine incomplete work, review the Sprint backlog for work that is still in a *Committed*, *Active*, or *In progress* state. :::image type="content" source="media/end-sprint/review-sprint-backlog.png" alt-text="Screenshot of Sprint Backlog at end of sprint."::: +> [!TIP] +> In Azure DevOps, closing a sprint doesn't automatically restrict updates to the sprint. Once a sprint gets closed, it's essential to manually move any unfinished work items to the current sprint or backlog. - + ### Reassign incomplete user stories and tasks to future sprint From the Sprint backlog, choose :::image type="icon" source="../../media/icons/view-options-icon.png" border="false"::: **View options** and select **Planning**. Drag and drop the work items that are incomplete to either the next sprint or back to the team backlog. -As shown in the following image, the **Fabrikam Team backlog** corresponds to the default **Iteration Path** set for the team. Note that if the default is set to the **@CurrentIteration** macro, then that selection wouldn't change the **Iteration Path** until the start of the next sprint. +As shown in the following image, the **Fabrikam Team backlog** corresponds to the default **Iteration Path** set for the team. If the default is set to the **@CurrentIteration** macro, then that selection wouldn't change the **Iteration Path** until the start of the next sprint. :::image type="content" source="media/end-sprint/reassign-planning-pane.png" alt-text="Screenshot of Sprint Backlog with Planning Pane enabled."::: ## Archive past sprints -Over time, the number of sprints defined for a project or assigned to a team can grow. To minimize the drop-down menu for Iteration paths, Project Administrators can choose to move past sprints to an archive area. By maintaining the sprint assignment, but moving it under a different sprint node, all work item data is retained. All sprint charts and widgets continue to work. +Over time, the number of sprints defined for a project or assigned to a team can grow. To minimize the drop-down menu for Iteration paths, Project Administrators can choose to move past sprints to an archive area. When you maintain the sprint assignment, but move it under a different sprint node, all work item data gets retained. All sprint charts and widgets continue to work. -As shown in the following image, sprints from 2012 and 2013 have been moved under the **Previous Sprints** node. +As shown in the following image, sprints from 2012 and 2013 were moved under the **Previous Sprints** node. :::image type="content" source="media/end-sprint/archived-sprints.png" alt-text="Screenshot of Iteration Paths archived under Previous Sprints node."::: > [!TIP] -> All data stored in work items is maintained by Azure DevOps until work items are permanently deleted. +> Azure DevOps maintains all data stored in work items until work items get permanently deleted. ## Sprint hygiene tips @@ -107,9 +103,7 @@ For more information, see [Define iteration paths (sprints) and configure team i - [Implement Scrum practices for your team in Azure Boards](scrum-overview.md) - [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) -- [View or configure team velocity](../../report/dashboards/team-velocity.md) -- [Sprint burndown](../../report/dashboards/configure-sprint-burndown.md) - \ No newline at end of file +- [Filter backlogs, boards, queries, and plans](../backlogs/filter-backlogs-boards-plans.md) +- [Use Scrum best practices](best-practices-scrum.md) +- [Plan your sprint](assign-work-sprint.md) +- [View or configure team velocity](../../report/dashboards/team-velocity.md) 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..aecbaa3688e 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 @@ -70,15 +64,15 @@ - name: Troubleshooting items: - name: FAQs - href: faqs.yml + href: faqs.yml?toc=/azure/devops/reference/toc.json + - name: Fix reordering and nesting issues + href: backlogs/resolve-backlog-reorder-issues.md?toc=/azure/devops/reference/toc.json + - name: Azure Boards customization FAQs + href: ../organizations/settings/work/faqs.yml?toc=/azure/devops/reference/toc.json - name: Set up your backlogs & boards - href: backlogs/set-up-your-backlog.md - - name: Fix "Ordering backlog items is disabled" - href: backlogs/resolve-backlog-reorder-issues.md - displayname: reorder, disable, nest, natural hierarchy, in progress + href: ../boards/backlogs/set-up-your-backlog.md?toc=/azure/devops/reference/toc.json - name: Work item form caching - href: ../organizations/settings/work/troubleshoot-work-item-form-caching-issues.md - displayname: IndexDB, rule + href: ../boards/faqs.yml#caching - name: Field reference items: - name: Work item field index @@ -90,12 +84,6 @@ href: work-items/guidance/guidance-code-review-feedback-field-reference.md - name: Bugs, issues, & risks fields href: work-items/guidance/cmmi/guidance-bugs-issues-risks-field-reference-cmmi.md - - name: Change request fields - href: /previous-versions/azure/devops/boards/work-items/guidance/cmmi/guidance-change-request-field-reference-cmmi - - name: Requirements fields - href: /previous-versions/azure/devops/boards/work-items/guidance/cmmi/guidance-requirements-field-reference-cmmi - - name: Review meeting fields - href: /previous-versions/azure/devops/boards/work-items/guidance/cmmi/guidance-review-meeting-field-reference-cmmi - name: CMMI process-specific fields (archived) items: - name: Change request fields 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..07a6326c931 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 @@ -1,71 +1,64 @@ --- title: Code review and feedback field reference titleSuffix: Azure Boards -description: Learn how to use the code review and feedback fields to track code review and feedback requests and responses for Azure Boards and Azure DevOps. +description: Learn how to use the code review and feedback fields to track code review and feedback requests and responses. ms.service: azure-devops-boards ms.assetid: 4182c1c5-a768-4f4d-b6cb-862fc57e6ab4 ms.topic: conceptual ms.author: chcomley author: chcomley monikerRange: '<= azure-devops' -ms.date: 11/07/2021 +ms.date: 05/12/2025 --- -# Code review and feedback field reference in Azure Boards and Azure DevOps +# Code review and feedback field reference [!INCLUDE [version-lt-eq-azure-devops](../../../includes/version-lt-eq-azure-devops.md)] -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. +This article provides a detailed reference for the fields used to track code reviews and feedback, including their descriptions, data types, and usage. It also explains how you can use these fields to monitor and manage code review and feedback workflows effectively. -::: 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 +Use the code review and feedback fields to create queries and reports that track the status of these processes. These fields are available for default work item types: Code Review Request, Code Review Response, Feedback Request, and Feedback Response. - + ## Fields used to track code reviews - The following fields are used to track code review requests and responses. You can only make a Code Review request against code maintained in a [Team Foundation version control (TFVC) repository](../../../repos/tfvc/index.yml). A code review response is created for each person who provides review comments. 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). +The following fields are used to track code review requests and responses. You can only make a Code Review request against code maintained in a [Team Foundation version control (TFVC) repository](../../../repos/tfvc/index.yml). A code review response is created for each person who provides review comments. 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). > [!NOTE] > Retrieving code review comments programmatically isn't a supported feature. - -> [!div class="mx-tdCol2BreakAll"] -> |**Field name**|**Description**|**Data type**| -> |--------------|---------------|-------------| -> |**Accepted By**|The name of the code reviewer.
Reference name=Microsoft.VSTS.CodeReview.AcceptedBy|String| -> |**Accepted Date**|The date and time when the code-reviewer responded.
Reference name=Microsoft.VSTS.CodeReview.AcceptedDate|DateTime| -> |**Associated Context**|The name assigned to the code work requested for review.
Reference name=Microsoft.VSTS.CodeReview.Context|String| -> |**Associated Context Code**|An integer value that captures whether the code review is for **1** (shelveset) or **2** (changeset).
Reference name=Microsoft.VSTS.CodeReview.ContextCode|Integer| -> |**Associated Context Owner**|The GUID assigned to the shelveset owner who requested the code review.
Reference name=Microsoft.VSTS.CodeReview.ContextOwner|String| -> |**Associated Context Type**|The type of code work requested for review: **Shelveset** or **Changeset**.
Reference name=Microsoft.VSTS.CodeReview.ContextType|String| -> |**Closed Status**|The status selected by the reviewer when closing the code review request. The number is stored in the system and written to the data warehouse as follows:

- **0 — Not Reviewed**
- **1 - Looks Good**
- **2 - With Comments**
- **3- Needs Work**
- **4 - Declined**
- **5 - Removed**
Reference name=Microsoft.VSTS.CodeReview.ClosedStatus|String| -> |**Closed Status Code**|A value ranging from 0 to 5 that corresponds to the status selected by the reviewer when closing the code review request.
Reference name=Microsoft.VSTS.CodeReview.ClosedStatusCode|Integer| -> |**Closing Comments**|The comment entered by the reviewer when closing the review request.
Reference name=Microsoft.VSTS.CodeReview.ClosingComment|String| -> |**Reviewed By**|The name of the team member who reviewed the code. The State transitions to Reviewed when the code reviewer responds. (Code Review Response)
Reference name=Microsoft.VSTS.Common.ReviewedBy|String| -> |**Reviewed Date**|The date-time stamp when the reviewer closed the request. (Code Review Response)
Reference name=Microsoft.VSTS.Common.ReviewedDate|Date-Time| -> |**State Code**|Mirror field used to track the current state in code.
Reference name=Microsoft.VSTS.Common.StateCode|Integer| +|**Field name**|**Description**|**Data type**| +|--------------|---------------|-------------| +|**Accepted By**|The name of the code reviewer.
Reference name=`Microsoft.CodeReview.AcceptedBy`|String| +|**Accepted Date**|The date and time when the code-reviewer responded.
Reference name=`Microsoft.CodeReview.AcceptedDate`|DateTime| +|**Associated Context**|The name assigned to the code work requested for review.
Reference name=`Microsoft.CodeReview.Context`|String| +|**Associated Context Code**|An integer value that captures whether the code review is for **1** (shelveset) or **2** (changeset).
Reference name=`Microsoft.CodeReview.ContextCode`|Integer| +|**Associated Context Owner**|The GUID assigned to the shelveset owner who requested the code review.
Reference name=`Microsoft.CodeReview.ContextOwner`|String| +|**Associated Context Type**|The type of code work requested for review: **Shelveset** or **Changeset**.
Reference name=`Microsoft.CodeReview.ContextType`|String| +|**Closed Status**|The status selected by the reviewer when closing the code review request. The number is stored in the system and written to the data warehouse as follows:

- **0—Not Reviewed**
- **1 - Looks Good**
- **2 - With Comments**
- **3- Needs Work**
- **4 - Declined**
- **5 - Removed**
Reference name=`Microsoft.CodeReview.ClosedStatus`|String| +|**Closed Status Code**|A value ranging from 0 to 5 that corresponds to the status selected by the reviewer when closing the code review request.
Reference name=`Microsoft.CodeReview.ClosedStatusCode`|Integer| +|**Closing Comments**|The comment entered by the reviewer when closing the review request.
Reference name=`Microsoft.CodeReview.ClosingComment`|String| +|**Reviewed By**|The name of the team member who reviewed the code. The State transitions to Reviewed when the code reviewer responds. (Code Review Response)
Reference name=`Microsoft.Common.ReviewedBy`|String| +|**Reviewed Date**|The date-time stamp when the reviewer closed the request. (Code Review Response)
Reference name=`Microsoft.Common.ReviewedDate`|Date-Time| +|**State Code**|Mirror field used to track the current state in code.
Reference name=`Microsoft.Common.StateCode`|Integer| ## Fields used to track feedback - The following fields track feedback requests and responses. You complete the first three fields in the feedback request form. A feedback response is created for each person and for each item for which feedback is provided. See [Get feedback](/previous-versions/azure/devops/project/feedback/get-feedback). +The following fields track feedback requests and responses. You complete the first three fields in the feedback request form. A feedback response is created for each person and for each item for which feedback is provided. See [Get feedback](/previous-versions/azure/devops/project/feedback/get-feedback). |**Field name**|**Description**|**Data type**| |--------------------|---------------------|-------------------| -|**Application Launch Instructions**|Instructions to stakeholders on how to start the application.
Reference name=Microsoft.VSTS.Feedback.ApplicationLaunchInstructions|HTML| -|**Application Start Information**|Guidelines to direct stakeholder feedback.
Reference name=Microsoft.VSTS.Feedback.ApplicationStartInformation|PlainText| -|**Application Type**|The type of application that stakeholders provide feedback on. The valid types are specified in the process configuration file, ProcessConfiguration. The default values are **Web Application**, **Remote Machine**, and **Client Application**.
Reference name=Microsoft.VSTS.Feedback.ApplicationType|String| -|**Rating**|The number of stars that an item receives from a reviewer in a star-based ranking system. (Feedback Response)
The number is stored in the system and written to the data warehouse as follows:

- **0 — Not Rated**
- **1 - Poor**
- **2 - Fair**
- **3- Good**
- **4- Very Good**
- **5 - Excellent**
Reference name=Microsoft.VSTS.Common.Rating|String| +|**Application Launch Instructions**|Instructions to stakeholders on how to start the application.
Reference name=`Microsoft.Feedback.ApplicationLaunchInstructions`|HTML| +|**Application Start Information**|Guidelines to direct stakeholder feedback.
Reference name=`Microsoft.Feedback.ApplicationStartInformation`|PlainText| +|**Application Type**|The type of application that stakeholders provide feedback on. The valid types are specified in the process configuration file, ProcessConfiguration. The default values are **Web Application**, **Remote Machine**, and **Client Application**.
Reference name=`Microsoft.Feedback.ApplicationType`|String| +|**Rating**|The number of stars that an item receives from a reviewer in a star-based ranking system. (Feedback Response)
The number is stored in the system and written to the data warehouse as follows:

- **0—Not Rated**
- **1 - Poor**
- **2 - Fair**
- **3- Good**
- **4- Very Good**
- **5 - Excellent**
Reference name=`Microsoft.Common.Rating`|String| ## Related articles -- [Index of work item fields](work-item-field.md) -- [Get feedback](/previous-versions/azure/devops/project/feedback/get-feedback) -- [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) \ No newline at end of file +- [Explore the index of work item fields](work-item-field.md) +- [Provide and gather feedback](/previous-versions/azure/devops/project/feedback/get-feedback) +- [Suspend work, fix a bug, and conduct a code review](../../../repos/tfvc/day-life-alm-developer-suspend-work-fix-bug-conduct-code-review.md) 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..70a17e4c933 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 [Create your backlog](../backlogs/create-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..fccc36ae1ca 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..e0c94f02460 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 @@ -22,14 +25,12 @@ - name: Manage issues href: ../backlogs/manage-issues-impediments.md displayname: impediment -- name: Link work items +- name: Link work items to objects 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-release-pipeline.md b/docs/cli/azure-devops-cli-in-release-pipeline.md index 00c4eb73619..809dafb87c9 100644 --- a/docs/cli/azure-devops-cli-in-release-pipeline.md +++ b/docs/cli/azure-devops-cli-in-release-pipeline.md @@ -1,14 +1,15 @@ --- title: Azure DevOps CLI in a release pipeline titleSuffix: Azure DevOps -description: Learn how to create a release pipeline using Azure DevOps CLI +description: Learn how to create a release pipeline using Azure DevOps CLI. This article includes a sample script. ms.topic: how-to ms.subservice: azure-devops-reference ms.manager: mijacobs ms.author: chcomley author: chcomley monikerRange: 'azure-devops' -ms.date: 08/17/2020 +ms.date: 06/05/2025 +#customer intent: As a developer, I want to create a release pipeline in Azure DevOps by using the Azure DevOps CLI. --- @@ -18,39 +19,35 @@ ms.date: 08/17/2020 -To use the Azure DevOps CLI in a hosted agent using a Release Pipeline, execute the following steps: +To use the Azure DevOps CLI in a hosted agent using a Release Pipeline, do the following steps: 1. Create a release pipeline. - > [!div class="mx-imgBorder"] - > ![new release pipeline](media/new-pipeline.png) + :::image type="content" source="media/new-pipeline.png" alt-text="Screenshot shows the Pipeline page with the option to create a new release pipeline."::: -2. Choose **Empty job**. +1. Select **Empty job**. - > [!div class="mx-imgBorder"] - > ![select template](media/select-template.png) + :::image type="content" source="media/select-template.png" alt-text="Screenshot shows the Select a template page with the Empty job link highlighted."::: -3. Choose Stage 1 to configure the stage. +1. Select Stage 1 to configure the stage. - > [!div class="mx-imgBorder"] - > ![Stage 1](media/stage-1.png) + :::image type="content" source="media/stage-1.png" alt-text="Screenshot shows the New release pipeline page with Stage 1 highlighted." lightbox="media/stage-1.png"::: -4. Choose the **Tasks** page, and configure the job to use Hosted macOS in Agent Pools. +1. Select the **Tasks** page, and configure the job to use Hosted macOS in Agent Pools. - > [!div class="mx-imgBorder"] - > ![Agent Job Configuration](media/job-config.png) + :::image type="content" source="media/job-config.png" alt-text="Screenshot shows the Tasks tab for Stage 1, which displays Agent job configuration." lightbox="media/job-config.png"::: -5. Choose the :::image type="icon" source="../media/icons/blue-add.png" border="false"::: plus icon to add another task and configure it as a PowerShell task. Enter *Power* into the search box to filter the list. +1. Select the :::image type="icon" source="../media/icons/blue-add.png" border="false"::: plus icon to add another task and configure it as a PowerShell task. To filter the list, enter *Power* into the search box. - > [!div class="mx-imgBorder"] - > ![PowerShell](media/power-shell.png) + :::image type="content" source="media/power-shell.png" alt-text="Screenshot shows the Tasks tab for Agent job with the Add tasks option." lightbox="media/power-shell.png"::: -6. Add the script, either via file or inline. For the example, the script has been included inline. +1. Add the script, either by using file or inline. For this example, the script is included inline. - > [!div class="mx-imgBorder"] - > ![Add script](media/script-1.png) + :::image type="content" source="media/script-1.png" alt-text="Screenshot shows an Azure PowerShell script included for the task." lightbox="media/script-1.png"::: -For reference, here is the inline script: +1. There might be more configuration steps for your pipeline. When you finish all steps, select **Save**. + +Here's the inline script for this example: ```powershell $extensions = az extension list -o json | ConvertFrom-Json @@ -67,4 +64,3 @@ if ($devopsFound -eq $False){ az extension add -n azure-devops } ``` - diff --git a/docs/cli/azure-devops-cli-in-yaml.md b/docs/cli/azure-devops-cli-in-yaml.md index 23da7927a98..a9c1d1fa7f0 100644 --- a/docs/cli/azure-devops-cli-in-yaml.md +++ b/docs/cli/azure-devops-cli-in-yaml.md @@ -1,64 +1,83 @@ --- title: Azure DevOps CLI in Azure Pipeline YAML titleSuffix: Azure DevOps -description: Use Azure DevOps CLI to create Azure Pipeline YAML +description: Learn how to use Azure DevOps CLI with a YAML pipeline with these examples that show how to run Azure DevOps CLI commands. 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: 05/30/2025 +#customer intent: As a team member, I want to use YAML configuration files to manage my pipeline tasks by using Azure DevOps CLI. --- # 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 want to use Azure DevOps CLI with a YAML pipeline, 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, like `az devops configure` and `az devops --help`, don't require any authentication. They don't connect into Azure DevOps. 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). -For more information about authentication using a personal access token, see [Sign in with a personal access token (PAT)](log-in-via-pat.md). +For more information about authentication using a personal access token (PAT), see [Sign in with a personal access token](log-in-via-pat.md). -## Azure DevOps CLI with Windows and Linux hosted agents +## Sign in to Azure DevOps CLI with Windows and Linux hosted agents -The Microsoft-hosted Windows and Linux agents are preconfigured with Azure CLI and the Azure DevOps CLI extension. +The Microsoft-hosted Windows and Linux agents are preconfigured with Azure CLI and the Azure DevOps CLI extension. -The following example shows how to log in to Azure DevOps and run a few commands. This example uses the `ubuntu-latest` Microsoft-hosted agent image, but you can replace it with any of the other [Windows or Linux hosted images](../pipelines/agents/hosted.md#software). +The following example shows how to sign in to Azure DevOps and run a few commands. This example uses the `ubuntu-latest` Microsoft-hosted agent image. You can replace it with any of the other [Windows or Linux hosted images](../pipelines/agents/hosted.md#software). -This example authenticates with Azure DevOps CLI using the [System.AccessToken](../pipelines/build/variables.md#systemaccesstoken) security token used by the running pipeline. +This example authenticates with Azure DevOps CLI. It uses 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,8 +88,33 @@ 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 +--- + +## Install Azure DevOps CLI extension with macOS hosted agents The macOS Microsoft-hosted agents have Azure CLI installed but not the Azure DevOps CLI extension. To install the Azure DevOps CLI extension, run the following command in your pipeline before making any Azure DevOps CLI calls. @@ -80,14 +124,16 @@ The macOS Microsoft-hosted agents have Azure CLI installed but not the Azure Dev displayName: 'Install Azure DevOps extension' ``` -## Hosted agent Azure CLI version +## Upgrade 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. In other cases, the tool is pinned to specific versions. -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). +- 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). -* 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). +You can upgrade the Azure CLI on your hosted images by running the following commands in your pipeline. -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. +# [Bash](#tab/bash) ```yml # Specify python version @@ -97,14 +143,31 @@ 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 +- bash: pip install --pre azure-cli displayName: 'Upgrade Azure CLI' ``` +# [PowerShell](#tab/powershell) + +```yml +# Specify python version +- task: UsePythonVersion@0 + inputs: + versionSpec: '3.x' + architecture: 'x64' + +# Update to latest Azure CLI version +- 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 virtual machine images, some of which don't have the Azure DevOps CLI extension installed, you can install conditionally. + +# [Bash](#tab/bash) ```yml trigger: @@ -113,16 +176,18 @@ trigger: # Run on multiple Microsoft-hosted agent images strategy: matrix: - linux18: - imageName: "ubuntu-18.04" - linux20: - imageName: "ubuntu-20.04" - mac1015: - imageName: "macos-10.15" - macOS11: - imageName: "macos-11" - windows2019: - imageName: "windows-2019" + linux24: + imageName: "ubuntu-24.04" + linux22: + imageName: "ubuntu-22.04" + mac15: + imageName: "macos-15" + mac14: + imageName: "macos-14" + mac13: + imageName: "macos-13" + windows2025: + imageName: "windows-2025" windows2022: imageName: "windows-2022" maxParallel: 3 @@ -141,7 +206,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,26 +219,83 @@ steps: displayName: 'Show build list and PRs' ``` +# [PowerShell](#tab/powershell) + +```yml +trigger: +- main + +# Run on multiple Microsoft-hosted agent images +strategy: + matrix: + linux24: + imageName: "ubuntu-24.04" + linux22: + imageName: "ubuntu-22.04" + mac15: + imageName: "macos-15" + mac14: + imageName: "macos-14" + mac13: + imageName: "macos-13" + windows2025: + imageName: "windows-2025" + 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, 'mac') + 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](#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). -* 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). +After you install Azure CLI, install the [Azure DevOps CLI extension](index.md). ### Install Azure CLI and Azure DevOps CLI extension in your pipeline 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. +- 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 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 +308,37 @@ 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' ``` -* 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). +# [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'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 +348,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 +378,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 +389,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 gets the ID of a variable group named **Fabrikam-2023** and uses this value in a subsequent step. + +# [Bash](#tab/bash) ```yml variables: @@ -242,27 +433,55 @@ 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 -* [System.AccessToken](../pipelines/build/variables.md#systemaccesstoken) -* [Access repositories, artifacts, and other resources](../pipelines/process/access-tokens.md) -* [Define variables](../pipelines/process/variables.md) -* [Azure DevOps CLI extension reference](/cli/azure/devops) -* [Azure DevOps CLI extension az pipelines reference](/cli/azure/pipelines) -* [How to query Azure CLI command output using a JMESPath query](/cli/azure/query-azure-cli) +- [System.AccessToken](../pipelines/build/variables.md#systemaccesstoken) +- [Access repositories, artifacts, and other resources](../pipelines/process/access-tokens.md) +- [Define variables](../pipelines/process/variables.md) +- [Azure DevOps CLI extension reference](/cli/azure/devops) +- [Azure DevOps CLI extension az pipelines reference](/cli/azure/pipelines) +- [How to query Azure CLI command output using a JMESPath query](/cli/azure/query-azure-cli) diff --git a/docs/cli/entra-tokens.md b/docs/cli/entra-tokens.md new file mode 100644 index 00000000000..fc3b98cdab5 --- /dev/null +++ b/docs/cli/entra-tokens.md @@ -0,0 +1,94 @@ +--- +ms.topic: how-to +title: Issue Entra tokens with Azure CLI +description: Use Microsoft Entra authentication on top of Azure CLI +ms.assetid: 19285121-1805-4421-B7C4-63784C9A7CFA +ms.subservice: azure-devops-security +monikerRange: 'azure-devops' +ms.author: chcomley +author: chcomley +ms.date: 05/12/2025 +--- + +# Issue Entra tokens with Azure CLI + +Use the [**Azure CLI**](/cli/azure/install-azure-cli) to issue a [Microsoft Entra token](../integrate/get-started/authentication/entra.md) and 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. You can use Azure CLI to acquire a user token for yourself or on behalf of a [service principal](../integrate/get-started/authentication/service-principal-managed-identity.md). + +## Prerequisites + +| Category | Requirements | +|------------|------------| +| Entra tenant and subscription    | 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 CLI     | Download and install the [Azure CLI](/cli/azure/install-azure-cli). | +| Entra app | (If authenticating for a service principal) Create the Entra application and have the app client ID and client secret ready. | + +## Acquiring an Entra token for yourself + +# [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' + ``` + +## Acquiring a token for a service principal + +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 + + # To authenticate a managed identity: + az login --identity + ``` + +3. Set the right correct subscription for the signed-in service principal by entering the command: + ``` powershell + az account set -s + ``` + +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 + ``` + +> [!NOTE] +> Use the Azure DevOps application ID, not our resource URI, for generating tokens. + +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 + ``` diff --git a/docs/cli/index.md b/docs/cli/index.md index ddc1e894c1e..fb6361a3b80 100644 --- a/docs/cli/index.md +++ b/docs/cli/index.md @@ -1,52 +1,57 @@ --- -title: Learn about Azure DevOps command line interface extension +title: Get Started with Azure DevOps CLI titleSuffix: Azure DevOps -description: Use Azure DevOps extension command line interface +description: Install the Azure DevOps extension command line interface. Learn how to sign on, configure defaults, access help, and open Azure DevOps services in a browser. ms.topic: quickstart ms.subservice: azure-devops-reference ms.manager: mijacobs ms.author: chcomley author: chcomley monikerRange: 'azure-devops' -ms.date: 08/17/2020 +ms.date: 05/30/2025 +#customer intent: As a project team member, I want to set up Azure DevOps CLI and understand how to access pipelines, boards, repos, and artifacts. --- -# Get started with Azure DevOps CLI +# Quickstart: Get started with Azure DevOps CLI -[!INCLUDE [version-eq-azure-devops](../includes/version-eq-azure-devops.md)] +[!INCLUDE [version-eq-azure-devops](../includes/version-eq-azure-devops.md)] -With the Azure DevOps extension for Azure Command Line Interface (CLI), you can manage many Azure DevOps Services from the command line. CLI commands enable you to streamline your tasks with faster and flexible interactive canvas, bypassing user interface workflows. +In this quickstart, you set up and start using the Azure DevOps extension for Azure Command Line Interface (CLI). With Azure CLI, you can manage many Azure DevOps Services from the command line. Azure CLI commands enable you to streamline your tasks with faster and flexible interactive canvas, bypassing user interface workflows. > [!NOTE] -> The Azure DevOps Command Line Interface (CLI) is only available for use with Azure DevOps Services. The Azure DevOps extension for the Azure CLI does not support any version of Azure DevOps Server. +> The Azure DevOps CLI is only available for use with Azure DevOps Services. The Azure DevOps extension for the Azure CLI doesn't support any version of Azure DevOps Server. -To start using the Azure DevOps extension for Azure CLI, perform the following steps: +To start using the Azure DevOps extension for Azure CLI: -1. Install Azure CLI: Follow the instructions provided in [Install the Azure CLI](/cli/azure/install-azure-cli) to set up your Azure CLI environment. At a minimum, your Azure CLI version must be 2.10.1. You can use `az --version` to validate. +1. Install Azure CLI. Follow the instructions in [Install the Azure CLI](/cli/azure/install-azure-cli) to set up your Azure CLI environment. At a minimum, your Azure CLI version must be 2.10.1. You can use the `az --version` command to validate. -2. Add the Azure DevOps extension: +1. Add the Azure DevOps extension. - ``` - az extension add --name azure-devops - ``` + ```azurecli + az extension add --name azure-devops + ``` - You can use `az extension list` or `az extension show --name azure-devops` to confirm the installation. +1. To confirm the installation, run the command `az extension list` or `az extension show --name azure-devops`. -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). +1. To sign in, run the `az login` command. Azure CLI supports only interactive sign-in using user name and password with `az login`. To sign in using a Personal Access Token (PAT), see [Sign in via Azure DevOps PAT](log-in-via-pat.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. + > [!NOTE] + > The Azure DevOps extension doesn't currently support authenticating by using [Managed Identities](../integrate/get-started/authentication/service-principal-managed-identity.md). - ``` - az devops configure --defaults organization=https://dev.azure.com/contoso project=ContosoWebApp - ``` +1. We recommend that you set the default configuration for your organization and project. Otherwise, you can specify the values in the individual commands themselves. -## Command usage + ```azurecli + az devops configure --defaults organization=https://dev.azure.com/contoso project=ContosoWebApp + ``` + +## Use commands Adding the Azure DevOps Extension adds `devops`, `pipelines`, `artifacts`, `boards`, and `repos` groups. -For usage and help content for any command, enter the **-h** parameter, for example: + +For usage and help content for any command, specify the `--help` parameter, for example: ```azurecli -az devops -h +az devops --help ``` ```output @@ -80,19 +85,17 @@ Commands: ## Open items in browser -You can use `--open` switch to open any artifact in Azure DevOps portal in your default browser. - -For example : +You can use `--open` parameter to open any artifact in Azure DevOps portal in your default browser. ```azurecli az pipelines build show --id 1 --open ``` -This command shows the details of build with `id 1` on the command-line and also opens it in the default browser. +This command shows the details of the build with `--id 1` in the Command Prompt window and also opens it in the default browser. ## Related articles -- [Sign in via Azure DevOps Personal Access Token (PAT)](log-in-via-pat.md) -- [Output formats](/cli/azure/format-output-azure-cli) -- [Index to az devops examples](quick-reference.md) +- [Sign in via Azure DevOps personal access token](log-in-via-pat.md) +- [Output formats for Azure CLI commands](/cli/azure/format-output-azure-cli) +- [Index to az devops CLI examples](quick-reference.md) - [Azure DevOps CLI Extension GitHub Repo](https://github.com/Azure/azure-devops-cli-extension) diff --git a/docs/cli/log-in-via-pat.md b/docs/cli/log-in-via-pat.md index e8dfafe69ed..9f25a420e0d 100644 --- a/docs/cli/log-in-via-pat.md +++ b/docs/cli/log-in-via-pat.md @@ -8,62 +8,66 @@ ms.manager: mijacobs ms.author: chcomley author: chcomley monikerRange: 'azure-devops' -ms.date: 08/17/2020 +ms.date: 06/05/2025 --- -# Sign in with a personal access token (PAT) +# Sign in with a personal access token [!INCLUDE [version-eq-azure-devops](../includes/version-eq-azure-devops.md)] -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). +This article explains how to sign in using an Azure DevOps personal access token (PAT). You can sign in [interactively with Microsoft Entra through the az login command](index.md) or by using an Azure DevOps PAT. To create a PAT, see [Use personal access tokens](../organizations/accounts/use-personal-access-tokens-to-authenticate.md#create-a-pat). -To use a PAT with the Azure DevOps CLI, use one of these options: +[!INCLUDE [use-microsoft-entra-reduce-pats](../includes/use-microsoft-entra-reduce-pats.md)] -* Use `az devops login` and be [prompted for the PAT token](#userprompt). -* Pipe the [PAT token on StdIn](#PipePATonStdIn) to `az devops login`. +To use a PAT with the Azure DevOps CLI, choose one of these methods: - > [!NOTE] - > This option works only in a non-interactive shell. +- Run `az devops login` and [enter the PAT token when prompted](#sign-in-with-a-personal-access-token). +- Pipe the [PAT token to StdIn](#pipe-a-pat-to-az-devops-login) and use it with `az devops login`. + > [!NOTE] + > This method works only in a non-interactive shell. +- Set the `AZURE_DEVOPS_EXT_PAT` [environment variable](#authenticate-with-the-azure_devops_ext_pat-environment-variable) and run CLI commands without using `az devops login`. -* Set the `AZURE_DEVOPS_EXT_PAT` [environment variable](#EnvironmentVariable), and don't use `az devops login`. +## Sign in with az devops login and enter your PAT -## User prompted to use az devops login - -You're prompted to enter a PAT after you run the `az devops login` command: +After you run the `az devops login` command, enter your personal access token (PAT) when prompted: ```azurecli -$az devops login --organization https://dev.azure.com/contoso +az devops login --organization https://dev.azure.com/contoso 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 already signed in interactively with `az login` or used a user name and password, you don't need to provide a PAT. The `az devops` commands now support sign-in through `az login`. + +When you sign in successfully, this command can also set your default organization if none is configured. -When you're successfully signed in, this command also can set your default organization to Contoso, provided no default organization is configured. +> [!NOTE] +> For Guest Users, only `az devops login` is supported. -## Pipe PAT on StdIn to az devops login +## Pipe a PAT to az devops login -### From a variable +You can provide your PAT to the Azure DevOps CLI by piping it to the `az devops login` command. This approach is useful for automation and CI/CD pipelines where interactive input isn't possible. -This option is useful in pipelines in which `#####` can be replaced by `$(System.AccessToken)` or another pipeline variable: +### Use a variable + +Replace `######` with `$(System.AccessToken)` or another pipeline variable: ```azurecli -echo "######" | az devops login --organization https://dev.azure.com/contoso/ +echo "######" | az devops login --organization https://dev.azure.com/contoso/ ``` -### From a file +### Use a file + +You can also store your PAT in a file and pipe it to the login command: ```azurecli cat my_pat_token.txt | az devops login --organization https://dev.azure.com/contoso/ ``` -## Use the AZURE_DEVOPS_EXT_PAT environment variable +## Authenticate with 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. +For non-interactive or automation scenarios, set the `AZURE_DEVOPS_EXT_PAT` environment variable to your PAT. If you haven't used `az login` or `az devops login`, all `az devops` commands attempt to use this variable for authentication. -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. - -To use a PAT, set the `AZURE_DEVOPS_EXT_PAT` environment variable at the process level. +Set the environment variable at the process level before running CLI commands to enable seamless authentication. #### [Windows](#tab/windows) @@ -75,10 +79,8 @@ $env:AZURE_DEVOPS_EXT_PAT = 'xxxxxxxxxx' ##### [macOS and Linux](#tab/unix) - ```bash export AZURE_DEVOPS_EXT_PAT=xxxxxxxxxx ``` Replace *xxxxxxxxxx* with your PAT. - 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..d0d05730213 100644 --- a/docs/cli/policy-configuration-file.md +++ b/docs/cli/policy-configuration-file.md @@ -1,72 +1,74 @@ --- -title: Configure branch policies for Azure DevOps CLI +title: Configure Branch Policies for Azure DevOps CLI titleSuffix: Azure DevOps -description: Configure branch policies using Azure DevOps CLI +description: Learn how to configure branch policies using Azure DevOps CLI to help your team protect their development branches. ms.topic: how-to ms.subservice: azure-devops-reference ms.manager: mijacobs ms.author: chcomley author: chcomley monikerRange: 'azure-devops' -ms.date: 04/30/2021 +ms.date: 06/03/2025 +#customer intent: As a team lead, I want to use branch policies to protected different development branches by using Azure DevOps CLI. --- # Configure Git repository policies using a configuration file -[!INCLUDE [version-eq-azure-devops](../includes/version-eq-azure-devops.md)] +[!INCLUDE [version-eq-azure-devops](../includes/version-eq-azure-devops.md)] Branch policies help teams protect their important branches of development. Policies enforce your team's code quality and change management standards. For an overview of policy settings you can configure, see [Git repository settings and policies](../repos/git/repository-settings.md). -You can configure branch policies for your repository using the various `az repos policy` commands. However, the policy commands accept a single scope, i.e., single combination of repository, branch and match type. If you want to apply the same policy across various scopes, you can do that using a policy configuration file. +You can configure branch policies for your repository using the various `az repos policy` commands. The policy commands accept a single scope. They work on a single combination of repository, branch, and match type. If you want to apply the same policy across various scopes, use a policy configuration file. -Say you want to create a manual queue build policy across all branch folders that start with "release" and also on the main branch. To achieve this, execute the following steps: +Say you want to create a manual queue build policy. It covers all branch folders that start with "release" and also on the main branch. -## Create a policy configuration file - -Create a policy configuration file for build policy, including the multiple application scopes. +First, create a policy configuration file for build policy, including the multiple application scopes. > [!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": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb" +> }, +> { +> "matchKind": "Exact", +> "refName": "refs/heads/main", +> "repositoryId": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb" +> } +> ], +> "validDuration": 0 > }, -> { -> "matchKind": "Exact", -> "refName": "refs/heads/main", -> "repositoryId": "e646f204-53c9-4153-9ab9-fd41a11e1234" +> "type": { +> "displayName": "Build", +> "id": "bbbbbbbb-1111-2222-3333-cccccccccccc" > } -> ], -> "validDuration": 0 -> }, -> "type": { -> "displayName": "Build", -> "id": "0609b952-1397-4640-95ec-e00a01b2f659" -> } > } > ``` -To learn more about the structure for various policy types, refer to [Policy create](/rest/api/azure/devops/policy/configurations/create#examples). +To learn more about the structure for various policy types, see [Policy create](/rest/api/azure/devops/policy/configurations/create#examples). -## Save the file and run the create policy command +Then, save the file and run the create policy command: -`az repos policy create C:\policyConfiguration.txt` +```azurecli +az repos policy create --policy-configuration C:\policyConfiguration.txt +``` -Note that the path is provided using '\\' backslash. +> [!NOTE] +> The path is provided using '\\' backslash. -## Related articles +## Related articles - [Git repository settings and policies](../repos/git/repository-settings.md) - diff --git a/docs/cli/quick-reference.md b/docs/cli/quick-reference.md index 4b690395eda..eb8ce1b2ea2 100644 --- a/docs/cli/quick-reference.md +++ b/docs/cli/quick-reference.md @@ -1,7 +1,7 @@ --- title: Index to Azure DevOps CLI examples titleSuffix: Azure DevOps -description: Find examples that showcase use of Azure DevOps CLI. +description: Find examples that showcase use of Azure DevOps CLI. This article contains an organized list of resources with examples. ms.topic: conceptual ms.subservice: azure-devops-reference ms.custom: devx-track-azurecli @@ -9,79 +9,76 @@ ms.manager: mijacobs ms.author: chcomley author: chcomley monikerRange: 'azure-devops' -ms.date: 11/08/2022 +ms.date: 05/30/2025 +#customer intent: As a team member who uses Azure DevOps CLI, I want to find examples to work from in different kinds areas of Azure DevOps. --- -# Index to Azure DevOps CLI examples - +# Index to Azure DevOps CLI examples [!INCLUDE [version-eq-azure-devops](../includes/version-eq-azure-devops.md)] -Use this index to quickly access examples that showcase use of the Azure DevOps Command Line Interface (CLI). +Use this index to quickly access examples that showcase use of the Azure DevOps Command Line Interface (CLI). -To start using Azure DevOps CLI, see [Get started with Azure DevOps CLI](index.md). +To start using Azure DevOps CLI, see [Get started with Azure DevOps CLI](index.md). > [!NOTE] -> The Azure DevOps Command Line Interface (CLI) is only available for use with Azure DevOps Services. The Azure DevOps extension for the Azure CLI does not support any version of Azure DevOps Server. +> The Azure DevOps Command Line Interface (CLI) is only available for use with Azure DevOps Services. The Azure DevOps extension for the Azure CLI doesn't support any version of Azure DevOps Server. ## Azure Artifacts -- [Universal Packages - download specific files](../artifacts/quickstarts/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) - +- [Universal Packages - download specific files](../artifacts/quickstarts/download-universal-packages.md#download-specific-files) +- [Create a feed](../artifacts/quickstarts/universal-packages.md#create-a-feed) +- [Download a universal package](../artifacts/quickstarts/download-universal-packages.md#download-universal-packages) +- [Publish a universal package](../artifacts/quickstarts/universal-packages.md#publish-universal-packages) + ## Azure Boards - :::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) - - [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) - - [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) + - [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) + - [Rename or move an iteration](../organizations/settings/set-iteration-paths-sprints.md#rename-or-move-an-iteration) + - [List project areas](../organizations/settings/set-area-paths.md#list-project-areas) + - [List project iterations](../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 iterations](../organizations/settings/set-iteration-paths-sprints.md#list-team-iterations) + - [Delete an area path](../organizations/settings/set-area-paths.md#delete-an-area-path) + - [Rename or move an 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#select-team-sprints-and-set-the-default-iteration-path) :::column-end::: :::column span="1"::: - #### Queries + #### Queries - [Run work item query](../boards/queries/view-run-query.md#run-a-query-in-azure-boards) - [Permanently delete work items](../boards/backlogs/remove-delete-work-items.md#az-boards-cli) #### Work items - [Add work items](../boards/work-items/view-add-work-items.md) - - [Add or remove work item links](../boards/backlogs/add-link.md#azure-cli) + - [Add or remove work item links](../boards/backlogs/add-link.md#link-a-work-item-to-another-work-item) - [Delete work items](../boards/backlogs/remove-delete-work-items.md#az-boards-cli) - [List supported link types](../boards/queries/link-type-reference.md#list-link-types) - - [Move work items](../boards/work-items/move-work-items.md#move-work-items) - - [Show work item details](../boards/backlogs/add-work-items.md#show-work-item) - - [Show work item link details](../boards/backlogs/add-link.md#azure-cli) - - [Update work items](../boards/backlogs/add-work-items.md#update-work-item) + - [Move work items](../boards/work-items/move-work-items.md#move-work-items) + - [Show work item details](../boards/backlogs/add-work-items.md#show-work-item) + - [Show work item link details](../boards/backlogs/add-link.md#link-a-work-item-to-another-work-item) + - [Update work items](../boards/backlogs/add-work-items.md#update-work-item) :::column-end::: :::row-end::: - -## Organizations, projects, and collections +## Organizations, projects, and collections :::row::: :::column span="1"::: #### Banners - - [Add a new banner](../organizations/settings/manage-banners.md) - - [List banners](../organizations/settings/manage-banners.md#list-banners) - - [Remove a banner](../organizations/settings/manage-banners.md#remove-a-banner) - - [Show banner details](../organizations/settings/manage-banners.md#list-banner-details) - - [Update a banner](../organizations/settings/manage-banners.md#update-a-banner) + - [Add a new banner](../organizations/settings/manage-banners.md?tabs=AzureCLI#add-a-banner) + - [List banners](../organizations/settings/manage-banners.md?tabs=AzureCLI#list-banners) + - [Remove a banner](../organizations/settings/manage-banners.md?tabs=AzureCLI#remove-a-banner) + - [Show banner details](../organizations/settings/manage-banners.md?tabs=AzureCLI#list-banner-details) + - [Update a banner](../organizations/settings/manage-banners.md?tabs=AzureCLI#update-a-banner) #### Extensions - - [Install an extension](../marketplace/install-extension.md) + - [Install an extension](../marketplace/install-extension.md) - [List extensions](../marketplace/install-extension.md#list-extensions) - [List extension information](../marketplace/install-extension.md#list-extension-information) - - [Search for extension in the Marketplace](../marketplace/overview.md#search-extension) - - [Uninstall/disable an extension](../marketplace/install-extension.md#uninstall-disable-extension) + - [Uninstall or disable an extension](../marketplace/install-extension.md#uninstall-disable-extension) #### Manage wikis - [Create a wiki](../project/wiki/manage-wikis.md#create-a-wiki) - [Create a wiki from a repo](../project/wiki/wiki-create-repo.md) @@ -90,32 +87,32 @@ To start using Azure DevOps CLI, see [Get started with Azure DevOps CLI](index.m - [Publish a repo as a wiki](../project/wiki/publish-repo-to-wiki.md) - [View wiki details](../project/wiki/manage-wikis.md#show-wiki) #### Projects - - [Create a project](../organizations/projects/create-project.md) - - [Delete a project](../organizations/projects/delete-project.md) - - [List projects](../organizations/projects/create-project.md#list-projects) - - [Show project information](../organizations/projects/create-project.md#show-project) - - [Open project in web portal](../organizations/projects/create-project.md#show-project) + - [Create a project](../organizations/projects/create-project.md) + - [Delete a project](../organizations/projects/delete-project.md) + - [List projects](../organizations/projects/create-project.md#list-projects) + - [Show project information](../organizations/projects/create-project.md?tabs=azure-devops-cli#list-projects-with-cli) + - [Open project in web portal](../organizations/projects/create-project.md?tabs=azure-devops-cli#show-project-information-in-the-web-portal) :::column-end::: :::column span="1"::: #### 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 teams](../organizations/settings/add-teams.md#list-teams) + - [Delete a team](../organizations/settings/rename-remove-team.md#delete-a-team) + - [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) + - [Rename a team](../organizations/settings/rename-remove-team.md#rename-a-team) #### User accounts - - [Add a user](../organizations/accounts/add-organization-users.md#add-user) - - [List users](../organizations/security/export-users-audit-log.md#list-users) - - [Remove a user](../organizations/accounts/delete-organization-users.md#remove-user) - - [Update a user](../organizations/accounts/add-organization-users.md#update-user) - - [Show users](../organizations/accounts/add-organization-users.md#show-users) + - [Add a user](../organizations/accounts/add-organization-users.md#add-users-to-your-organization) + - [List users](../organizations/security/export-users-audit-log.md?tabs=azure-devops-cli#list-users) + - [Remove a user](../organizations/accounts/delete-organization-users.md?tabs=azure-devops-cli#remove-user) + - [Update a user](../organizations/accounts/add-organization-users.md?tabs=azure-devops-cli#update-a-user) + - [Show users](../organizations/accounts/add-organization-users.md?tabs=azure-devops-cli#show-users) #### Wiki pages - [Add a wiki page](../project/wiki/add-edit-wiki.md#add-a-wiki-page) - - [Delete a wiki page](../project/wiki/add-edit-wiki.md#delete-wiki-page) - - [Edit a wiki page](../project/wiki/add-edit-wiki.md#edit-wiki-page) - - [Open a wiki](../project/wiki/add-edit-wiki.md#open-wiki) - - [View a wiki page](../project/wiki/add-edit-wiki.md#view-a-wiki-page) + - [Delete a wiki page](../project/wiki/add-edit-wiki.md?tabs=azure-devops-cli#delete-wiki-page) + - [Edit a wiki page](../project/wiki/add-edit-wiki.md?tabs=azure-devops-cli#edit-wiki-page) + - [Open a wiki](../project/wiki/add-edit-wiki.md?tabs=azure-devops-cli#open-wiki) + - [View a wiki page](../project/wiki/add-edit-wiki.md?tabs=azure-devops-cli#view-a-wiki-page) :::column-end::: :::row-end::: @@ -124,18 +121,18 @@ To start using Azure DevOps CLI, see [Get started with Azure DevOps CLI](index.m :::row::: :::column span="1"::: #### Add and run a pipeline - - [Create a pipeline](../pipelines/get-started/manage-pipelines-with-azure-cli.md) + - [Create a pipeline](../pipelines/get-started/manage-pipelines-with-azure-cli.md) - [Run a pipeline](../pipelines/get-started/manage-pipelines-with-azure-cli.md#run-a-pipeline) - [Show the details of a pipeline](../pipelines/get-started/manage-pipelines-with-azure-cli.md#show-pipeline) - [Update a pipeline](../pipelines/get-started/manage-pipelines-with-azure-cli.md#update-a-pipeline) #### Agents, agent pools, agent queues - - [List agents](../pipelines/agents/agents.md#list-agents) - - [List agent pools](../pipelines/agents/pools-queues.md#list-agent-pools) - - [List agent queues](../pipelines/agents/pools-queues.md#list-agent-queues) - - [Show agent details](../pipelines/agents/agents.md#show-agent-details) - - [Show agent pool details](../pipelines/agents/pools-queues.md#show-agent-pool-details) - - [Show agent queue details](../pipelines/agents/pools-queues.md#show-agent-queue-details) + - [List agents](../pipelines/agents/agents.md?tabs=yaml%2Cazure-devops-cli#list-agents) + - [List agent pools](../pipelines/agents/pools-queues.md?tabs=yaml%2Cazure-devops-cli#list-agent-pools) + - [List agent queues](../pipelines/agents/pools-queues.md?tabs=yaml%2Cazure-devops-cli#list-agent-queues) + - [Show agent details](../pipelines/agents/agents.md?tabs=yaml%2Cazure-devops-cli#show-agent-details) + - [Show agent pool details](../pipelines/agents/pools-queues.md?tabs=yaml%2Cazure-devops-cli#show-agent-pool-details) + - [Show agent queue details](../pipelines/agents/pools-queues.md?tabs=yaml%2Cazure-devops-cli#show-agent-queue-details) #### Artifacts - [Download your artifact](../pipelines/artifacts/pipeline-artifacts.md#download-artifacts) @@ -150,25 +147,25 @@ To start using Azure DevOps CLI, see [Get started with Azure DevOps CLI](index.m - [Show pipeline run details](../pipelines/process/runs.md#show-pipeline-run-details) #### Variables - - [Create a variable](../pipelines/process/variables.md#create-variable) - - [Delete a variable](../pipelines/process/variables.md#delete-variable) + - [Create a variable](../pipelines/process/variables.md?tabs=azure-devops-cli%2Cbatch#create-a-variable) + - [Delete a variable](../pipelines/process/variables.md?tabs=azure-devops-cli%2Cbatch#delete-a-variable) - [List variables](../pipelines/process/variables.md#list-variables) - - [Update a variable](../pipelines/process/variables.md#update-variable) + - [Update a variable](../pipelines/process/variables.md?tabs=azure-devops-cli%2Cbatch#update-a-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) - - [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) + - [Add variables to a variable group](../pipelines/library/variable-groups.md?tabs=azure-devops-cli%2Cyaml#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?tabs=azure-devops-cli%2Cyaml#delete-variables-from-a-variable-group) + - [List variable groups](../pipelines/library/variable-groups.md?tabs=azure-devops-cli%2Cyaml#list-variable-groups) + - [List variables in a variable group](../pipelines/library/variable-groups.md?tabs=azure-devops-cli%2Cyaml#list-variables-in-a-variable-group) + - [Show details for a variable group](../pipelines/library/variable-groups.md?tabs=azure-devops-cli%2Cyaml#show-details-for-a-variable-group) + - [Update a variable group](../pipelines/library/variable-groups.md?tabs=azure-devops-cli%2Cyaml#update-a-variable-group) + - [Update variables in a variable group](../pipelines/library/variable-groups.md?tabs=azure-devops-cli%2Cyaml#update-variables-in-a-variable-group) :::column-end::: :::row-end::: -## Azure Repos +## Azure Repos :::row::: :::column span="1"::: @@ -176,43 +173,43 @@ To start using Azure DevOps CLI, see [Get started with Azure DevOps CLI](index.m - [Create a repository](../repos/git/share-your-code-in-git-cmdline.md) - [Delete a repository](../repos/git/delete-existing-repo.md) - [Import a repository](../repos/git/import-git-repository.md) - - [List repositories](../repos/git/repository-settings.md#repos-list) + - [List repositories](../repos/git/repository-settings.md?tabs=azure-devops-cli#list-repositories) - [Rename a repository](../repos/git/repo-rename.md) - - [Show repository details](../repos/git/repository-settings.md#repos-show) - - [Update a repository](../repos/git/repository-settings.md#repos-update) + - [Show repository details](../repos/git/repository-settings.md?tabs=azure-devops-cli#list-repository-details) + - [Update a repository](../repos/git/repository-settings.md?tabs=azure-devops-cli#update-a-repository) #### Manage repository policies - - [List repository policies](../repos/git/repository-settings.md#repos-policy-list) - - [Show repository policies](../repos/git/repository-settings.md#show-policy) - - [Manage case enforcement policy](../repos/git/repository-settings.md#create-case-enforcement-policy) - - [Manage file size policy](../repos/git/repository-settings.md#create-file-size-policy) - - [Update repository policy](../repos/git/repository-settings.md#update-policy) + - [List repository policies](../repos/git/repository-settings.md?tabs=azure-devops-cli#list-policies) + - [Show repository policies](../repos/git/repository-settings.md?tabs=azure-devops-cli#show-policy-details) + - [Manage case enforcement policy](../repos/git/repository-settings.md?tabs=azure-devops-cli#create-case-enforcement-policy) + - [Manage file size policy](../repos/git/repository-settings.md?tabs=azure-devops-cli#create-file-size-policy) + - [Update repository policy](../repos/git/repository-settings.md?tabs=azure-devops-cli#update-policies) #### Manage branch policies - [List branch policies](../repos/git/branch-policies.md#configure-branch-policies) - - [Show branch policy](../repos/git/branch-policies.md#show-details-of-a-policy) + - [Show branch policy](../repos/git/branch-policies.md?tabs=azure-devops-cli#show-details-of-a-policy) - [Create policies using a configuration file](/cli/azure/repos/policy#az-repos-policy-create) - [Update policies using a configuration file](/cli/azure/repos/policy#az-repos-policy-update) - [Manage required reviewer policy](../repos/git/branch-policies.md#require_reviewers) - [Manage external required reviewer policies](../repos/git/branch-policies.md#require-approval-from-external-services) - [Manage build validation policies](../repos/git/branch-policies.md#build-validation) - - [Manage comment-required policy](../repos/git/branch-policies.md#check-comment-resolution) - - [Manage merge strategy policy](../repos/git/branch-policies.md#limit-merge-types) - - [Create work item linking policy](../repos/git/branch-policies.md#create-wi-policy) - - [Update work item linking policy](../repos/git/branch-policies.md#update-wi-policy) + - [Manage comment-required policy](../repos/git/branch-policies.md#check-comment-resolution) + - [Manage merge strategy policy](../repos/git/branch-policies.md#limit-merge-types) + - [Create work item linking policy](../repos/git/branch-policies.md?tabs=azure-devops-cli#create-work-item-linking-policy) + - [Update work item linking policy](../repos/git/branch-policies.md?tabs=azure-devops-cli#update-work-item-linking-policy) :::column-end::: :::column span="1"::: #### Pull requests - - [Create a pull request](../repos/git/pull-requests.md#create-a-new-pull-request) + - [Create a pull request](../repos/git/pull-requests.md#create-a-new-pull-request) - [Create a draft pull request](../repos/git/pull-requests.md#draft-pull-requests) - - [Edit a pull request, add details](../repos/git/pull-requests.md#add-details-pr) - - [Add reviewers to a pull request](../repos/git/pull-requests.md#add-and-remove-reviewers) + - [Edit a pull request, add details](../repos/git/pull-requests.md?tabs=azure-devops-cli#add-or-edit-pull-request-title-and-description) + - [Add reviewers to a pull request](../repos/git/pull-requests.md#add-and-remove-reviewers) - [Link work items to a pull request](../repos/git/pull-requests.md#link-work-items) - [List pull requests](../repos/git/view-pull-requests.md#list-pull-requests) - [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 completion options](../repos/git/complete-pull-requests.md?tabs=azure-devops-cli#set-completion-options) - [Set pull request to autocomplete](../repos/git/complete-pull-requests.md#complete-automatically) - [Abandon a pull request](../repos/git/complete-pull-requests.md#abandon-pr) - [Manage pull request policies](/cli/azure/repos/pr/policy) @@ -226,33 +223,29 @@ To start using Azure DevOps CLI, see [Get started with Azure DevOps CLI](index.m :::column-end::: :::row-end::: - - ## Security groups and permissions -- [Add a member to a security group](../organizations/security/add-manage-security-groups.md) -- [Assign allow or deny permission to specified user or group](../organizations/security/manage-tokens-namespaces.md) -- [Clear all permissions of this token for a user or group](../organizations/security/manage-tokens-namespaces.md) -- [Create a security group](../organizations/security/add-manage-security-groups.md) -- [Delete a security group](../organizations/security/add-manage-security-groups.md) -- [List tokens for specified user or group and namespace](../organizations/security/manage-tokens-namespaces.md) -- [List all available namespaces for an organization](../organizations/security/manage-tokens-namespaces.md) -- [List security groups](../organizations/security/add-manage-security-groups.md) -- [List the memberships for a group or user](../organizations/security/add-manage-security-groups.md) -- [Remove a member from a security group](../organizations/security/add-manage-security-groups.md) -- [Reset permission for specified permission bit(s)](../organizations/security/manage-tokens-namespaces.md) -- [Show details of a security group](../organizations/security/add-manage-security-groups.md) -- [Show details of permissions available in each namespace](../organizations/security/manage-tokens-namespaces.md) -- [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) - - +- [Add a member to a security group](../organizations/security/add-manage-security-groups.md#add-a-member-to-a-group) +- [Assign allow or deny permission to specified user or group](../organizations/security/manage-tokens-namespaces.md#update-permissions) +- [Clear all permissions of this token for a user or group](../organizations/security/manage-tokens-namespaces.md#reset-all-permissions) +- [Create a security group](../organizations/security/add-manage-security-groups.md#create-a-security-group) +- [Delete a security group](../organizations/security/add-manage-security-groups.md#delete-a-security-group) +- [List tokens for specified user or group and namespace](../organizations/security/manage-tokens-namespaces.md#list-tokens-for-a-security-namespace) +- [List all available namespaces for an organization](../organizations/security/manage-tokens-namespaces.md#list-security-namespaces) +- [List security groups](../organizations/security/add-manage-security-groups.md#list-security-groups) +- [List the memberships for a group or user](../organizations/security/add-manage-security-groups.md#list-memberships-for-a-group-or-user) +- [Remove a member from a security group](../organizations/security/add-manage-security-groups.md#remove-a-member-from-a-group) +- [Reset permission for specified permission bit(s)](../organizations/security/manage-tokens-namespaces.md#reset-permissions) +- [Show details of a security group](../organizations/security/add-manage-security-groups.md#show-security-group-details) +- [Show details of permissions available in each namespace](../organizations/security/manage-tokens-namespaces.md#show-namespace-details) +- [Show permissions for specified token, namespace, and user or group](../organizations/security/manage-tokens-namespaces.md#show-permissions) +- [Update a security group](../organizations/security/add-manage-security-groups.md#update-a-security-group) ## Service endpoints or service connections -- [Create a GitHub service endpoint](service-endpoint.md) -- [Create an Azure RM service endpoint](service-endpoint.md) -- [Create service endpoint using a configuration file](service-endpoint.md) +- [Create a GitHub service endpoint](service-endpoint.md#create-a-github-service-endpoint) +- [Create an Azure RM service endpoint](service-endpoint.md#create-an-azure-resource-manager-service-endpoint) +- [Create service endpoint using a configuration file](service-endpoint.md#create-service-endpoint-using-a-configuration-file) - [List service endpoints](/cli/azure/devops/service-endpoint#az-devops-service-endpoint-list) - [Delete a service endpoint](/cli/azure/devops/service-endpoint#az-devops-service-endpoint-delete) - [Manage GitHub service endpoints](/cli/azure/devops/service-endpoint/github) @@ -260,14 +253,14 @@ To start using Azure DevOps CLI, see [Get started with Azure DevOps CLI](index.m - [Update a service endpoint](/cli/azure/devops/service-endpoint#az-devops-service-endpoint-update) ## Related articles - + - [Cross-service integration overview](../cross-service/cross-service-overview.md) - [witAdmin: Customize and manage objects for tracking work](../reference/witadmin/witadmin-customize-and-manage-objects-for-tracking-work.md) ## Azure CLI reference articles -- [az artifacts](/cli/azure/azure-cli-reference-for-devops#azure-artifacts) -- [az boards](/cli/azure/azure-cli-reference-for-devops#azure-boards) -- [az devops](/cli/azure/azure-cli-reference-for-devops#azure-devops-organizations) -- [az pipelines](/cli/azure/azure-cli-reference-for-devops#azure-pipelines) -- [az repos](/cli/azure/azure-cli-reference-for-devops#azure-repos) +- [az artifacts](/cli/azure/artifacts) +- [az boards](/cli/azure/boards) +- [az devops](/cli/azure/devops) +- [az pipelines](/cli/azure/pipelines) +- [az repos](/cli/azure/repos) diff --git a/docs/cli/service-endpoint.md b/docs/cli/service-endpoint.md index 3b617c12eba..b30f3f317b3 100644 --- a/docs/cli/service-endpoint.md +++ b/docs/cli/service-endpoint.md @@ -1,65 +1,71 @@ --- -title: Create service endpoint using Azure DevOps CLI +title: Create Service Endpoint Using Azure DevOps CLI titleSuffix: Azure DevOps -description: Learn how to use Azure DevOps CLI to create a service endpoint +description: Learn how to use Azure DevOps CLI to create a service endpoint. You can create and manage different types of service connections. ms.topic: how-to ms.subservice: azure-devops-reference -ms.custom: devx-track-arm-template ms.manager: mijacobs ms.author: chcomley author: chcomley monikerRange: 'azure-devops' -ms.date: 06/13/2022 +ms.date: 06/03/2025 +ms.custom: + - devx-track-arm-template + - devx-track-azurecli + - arm2024 + - sfi-image-nochange +#customer intent: As a developer, I want to use Azure DevOps CLI to create and manage different types of service connections. --- # Azure DevOps CLI service endpoint -[!INCLUDE [version-eq-azure-devops](../includes/version-eq-azure-devops.md)] +[!INCLUDE [version-eq-azure-devops](../includes/version-eq-azure-devops.md)] -With the `az devops service-endpoint` command, you can create and manage different types of service connections. A service connection allows Azure DevOps to communicate with an external service, such as Azure, Bitbucket, Kubernetes, Maven, GitHub, and more. With `az devops service-endpoint`, you can perform the following tasks: +A *service connection* allows Azure DevOps to communicate with an external service, such as Azure, Bitbucket, Kubernetes, Maven, and GitHub. With the `az devops service-endpoint` command, you can create and manage different types of service connections. You can accomplish the following tasks: -- Create a service endpoint using a configuration file +- Create a service endpoint by using a configuration file - Update a service endpoint -- Manage GitHub service endpoints/connections -- Manage Azure Resource Manager service endpoints/connections -- List service endpoints defined for a project -- Get the details of a service endpoint. +- Manage GitHub service endpoints and connections +- Manage Azure Resource Manager service endpoints and connections +- List service endpoints defined for a project +- Get the details of a service endpoint -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). +For detailed 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 use Azure CLI commands to get details, list, delete, and update a service endpoint. See [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). - +To use the web portal to create and edit service connections, see [Manage service connections](../pipelines/library/service-endpoints.md). -## Create service endpoint using a configuration file +[!INCLUDE [use-service-principals-tip](../includes/use-service-principals-tip.md)] -To create a service endpoint using a configuration file, you must first define the configuration file. The contents of the configuration file differ depending on the type of connection, such as Azure Classic, Azure Data Explorer, Bitbucket Cloud, Chef, and more. +## Create service endpoint using a configuration file -### Configuration file format +To create a service endpoint by using a configuration file, first define the configuration file. The contents of the configuration file differ depending on the type of connection, such as Azure Classic, Azure Data Explorer, Bitbucket Cloud, or Chef. -The following syntax shows the `json` format for the configuration file. +### Configuration file format + +The following syntax shows the JSON format for the configuration file. > [!div class="tabbedCodeSnippets"] -```json + +```json { "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, "serviceEndpointProjectReferences": [ { "projectReference": { - "id": "c7e5f0b3-71fa-4429-9fb3-3321963a7c06", + "id": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb", "name": "TestProject" }, "name": "MyNewServiceEndpoint" @@ -68,65 +74,70 @@ The following syntax shows the `json` format for the configuration file. } ``` -The following table describes each parameter. The `type` parameter supports creation of any type of service endpoint. - +The following table describes each parameter. The `type` parameter supports creation of any type of service endpoint. | Parameter | Type | Description | |---------------------|-----------------------|---------------| -| `name` | string| Sets the friendly name of the endpoint.| -| `type` | string| Sets the type of the endpoint. | -| `url` | string| Sets the url of the endpoint. | -| `authorization` | EndpointAuthorization | Sets the authorization data for talking to the endpoint. | -| `isShared` | boolean| Indicates whether the service endpoint is shared with other projects or not. | -| `isReady` | boolean| EndPoint state indicator. | -| `serviceEndpointProjectReferences` | Project Reference | Sets project reference of the service endpoint. | - - -For a list of supported types and their required input parameters, you can exercise the following REST API entry: +| `name` | string | Sets the friendly name of the endpoint. | +| `type` | string | Sets the type of the endpoint. | +| `url` | string | Sets the url of the endpoint. | +| `authorization` | EndpointAuthorization | Sets the authorization data for talking to the endpoint. | +| `isShared` | boolean| Indicates whether the service endpoint is shared with other projects. | +| `isReady` | boolean| EndPoint state indicator. | +| `serviceEndpointProjectReferences` | Project Reference | Sets project reference of the service endpoint. | + +For a list of supported types and their required input parameters, review the following REST API entry: + +```http +https://dev.azure.com/{organization}/_apis/serviceendpoint/types?api-version=6.0-preview.1 +``` -```https://dev.azure.com/{organization}/_apis/serviceendpoint/types?api-version=6.0-preview.1``` +For a description of service connection types and parameters, see [Common service connection types](../pipelines/library/service-endpoints.md#common-service-connection-types). -Also, for a description of service connection types and other parameters that they may require, see [Manage service connections, Common service connection types](../pipelines/library/service-endpoints.md#common-service-connection-types). - ### Run the `create` command -You create a service endpoint with the [`az devops service-endpoint create`](/cli/azure/devops/service-endpoint#az-devops-service-endpoint-create) command. +You create a service endpoint with the [az devops service-endpoint create](/cli/azure/devops/service-endpoint#az-devops-service-endpoint-create) command. > [!div class="tabbedCodeSnippets"] -```Azure CLI + +```azurecli az devops service-endpoint create --service-endpoint-configuration [--encoding {ascii, utf-16be, utf-16le, utf-8}] - [--org] + [--organization] [--project] ``` - ### Parameters -- **service-endpoint-configuration**: Required. Name of the `json` configuration file with service endpoint configuration. +- **service-endpoint-configuration**: Required. Name of the `json` configuration file with service endpoint configuration. - **encoding**: Optional. Encoding of the input file. Default is `utf-8`. Accepted values: `ascii`, `utf-16be`, `utf-16le`, `utf-8`. -- **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. -- **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. +- **organization**: Azure DevOps organization URL. You can configure the default organization using `az devops configure --defaults organization=ORG_URL`. Required if not configured as default. +- **project**: Name or ID of the project. You can configure the default project using `az devops configure --defaults project=NAME_OR_ID`. Required if not configured as default. ### Example -The following command creates a service connection referencing the `ServiceConnectionGeneric.json` file. - + +The following command creates a service connection referencing the *ServiceConnectionGeneric.json* file. + > [!div class="tabbedCodeSnippets"] + ```Azure CLI az devops service-endpoint create --service-endpoint-configuration ./ServiceConnectionGeneric.json ``` -Upon successful creation, an `Id` is assigned to the service endpoint and a response similar to the following syntax is returned. + +After creation, the command assigns an `Id` to the service endpoint. This example returns the following result. > [!div class="tabbedCodeSnippets"] -```Azure CLI + +```azurecli { "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", @@ -168,39 +179,39 @@ Upon successful creation, an `Id` is assigned to the service endpoint and a resp ## Create a GitHub service endpoint -To create a GitHub service endpoint, use the [`az devops service-endpoint github create`](/cli/azure/devops/service-endpoint/github) command: +To create a GitHub service endpoint, use the [az devops service-endpoint github create](/cli/azure/devops/service-endpoint/github) command: > [!div class="tabbedCodeSnippets"] -```Azure CLI + +```azurecli az devops service-endpoint github create --github-url --name - [--org] + [--organization] [--project] ``` -In interactive mode, the `az devops service-endpoint github create` command asks for a [GitHub PAT token](https://help.github.com/en/articles/creating-a-personal-access-token-for-the-command-line) using a prompt message, for automation purpose set the GitHub PAT token using the `AZURE_DEVOPS_EXT_GITHUB_PAT` environment variable. For more information, see [Sign in with a personal access token (PAT)](log-in-via-pat.md). - - +In interactive mode, the `az devops service-endpoint github create` command prompts you for [GitHub PAT token](https://help.github.com/en/articles/creating-a-personal-access-token-for-the-command-line). For automation purposes, set the GitHub PAT token using the `AZURE_DEVOPS_EXT_GITHUB_PAT` environment variable. For more information, see [Sign in with a personal access token](log-in-via-pat.md). ## Create an Azure Resource Manager service endpoint -To create an Azure Resource Manager service endpoint, use the [`az devops service-endpoint azurerm create`](/cli/azure/devops/service-endpoint/azurerm) command. +To create an Azure Resource Manager service endpoint, use the [az devops service-endpoint azurerm create](/cli/azure/devops/service-endpoint/azurerm) command. > [!div class="tabbedCodeSnippets"] -```Azure CLI + +```azurecli az devops service-endpoint azurerm create --azure-rm-service-principal-id --azure-rm-subscription-id --azure-rm-subscription-name --azure-rm-tenant-id --name [--azure-rm-service-principal-certificate-path] - [--org] + [--organization] [--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 prompts you for a service principal secret. 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 +223,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), create a .pem file for the certificate. 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) -- [`az devops service-endpoint`](/cli/azure/devops/service-endpoint) -- [Endpoints REST API](/rest/api/azure/devops/serviceendpoint/endpoints) - - - +- [Connect to Azure with an Azure Resource Manager service connection](../pipelines/library/connect-to-azure.md) +- [az devops service-endpoint](/cli/azure/devops/service-endpoint) +- [Endpoints REST API](/rest/api/azure/devops/serviceendpoint/endpoints) diff --git a/docs/cli/toc.yml b/docs/cli/toc.yml index e089d63ad5e..00781d0bd2d 100644 --- a/docs/cli/toc.yml +++ b/docs/cli/toc.yml @@ -4,6 +4,8 @@ href: quick-reference.md - name: Sign in with a Personal Access Token href: log-in-via-pat.md +- name: Acquire an Entra token + href: entra-tokens.md - name: Auto detect configuration and git aliases href: auto-detect-and-git-aliases.md - name: Configure policies diff --git a/docs/cross-service/cross-service-overview.md b/docs/cross-service/cross-service-overview.md index be82ba4d8db..c1e2a6ac88d 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). | -## 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..ee51de5065f 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 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..96993b5b239 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 + - name: Link work items to objects + 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..ab58d0232cd 100644 --- a/docs/demo-gen/build-your-own-template.md +++ b/docs/demo-gen/build-your-own-template.md @@ -7,6 +7,7 @@ author: hsachinraj ms.topic: conceptual monikerRange: 'azure-devops' ms.date: 05/24/2023 +ms.custom: sfi-image-nochange --- # Build a custom template @@ -17,7 +18,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..fb4030418e9 --- /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](https://github.com/microsoft/AzDevOpsDemoGenerator) 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. 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..c1be8321d3a 100644 --- a/docs/demo-gen/use-demo-generator-v2.md +++ b/docs/demo-gen/use-demo-generator-v2.md @@ -1,88 +1,75 @@ --- title: Use Azure DevOps Demo Generator -description: Use the Azure DevOps Services Demo Generator V2 to create and populate a demo project +description: Use the Azure DevOps Services Demo Generator V2 to create and populate a demo project. ms.subservice: azure-devops-new-user ms.author: sdanie ms.topic: conceptual monikerRange: 'azure-devops' -ms.date: 10/10/2019 +ms.date: 06/06/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. +This article explains how to use the **Azure DevOps Demo Generator** application to quickly create a new Azure DevOps project prepopulated with sample content, such as work items, repositories, and other resources needed for labs and demonstrations. -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. +## Prerequisites - > [!div class="mx-imgBorder"] - > :::image type="content" source="media/homepage.png" alt-text="Azure DevOps Demo Generator V2 login" lightbox="media/homepage.png"::: +Set up the Demo Generator application by following the steps in the [configure section](configure.md). - > [!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. +## Select your authentication method for Demo Generator -1. After you sign in, select **Accept** to grant the Demo Generator permissions to access your Azure DevOps organization. +Use one of the following methods to authenticate to the Azure DevOps Demo Generator app: - > [!div class="mx-imgBorder"] - > :::image type="content" source="media/2.png" alt-text="Azure DevOps Demo Generator V2 permissions screen" lightbox="media/2.png"::: +- **Microsoft Entra:** [Register your application in Microsoft Entra](/entra/identity-platform/quickstart-register-app?tabs=certificate%2Cexpose-a-web-api#register-an-application). -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. + * Sign in with the displayed code. + * Select an organization to create a project from the list. - > [!div class="mx-imgBorder"] - > :::image type="content" source="media/templateselection.png" alt-text="Azure DevOps Demo Generator template selection screen" lightbox="media/templateselection.png"::: +[!INCLUDE [use-microsoft-entra-reduce-pats](../includes/use-microsoft-entra-reduce-pats.md)] - 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. +- **Personal Access Token (PAT):** Sign in with a [Personal Access Token (PAT)](../organizations/accounts/use-personal-access-tokens-to-authenticate.md#creating-pats) with the following scopes: - 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 + | 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] - > 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. + Enter the organization name and the PAT. Provide the project name and press enter to create a project -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. + > [!div class="mx-imgBorder"] + > [![Screenshot shows 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) - > [!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. +## Create your demo 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. +To create your demo project, do the following steps: - > [!div class="mx-imgBorder"] - > :::image type="content" source="media/projectcreated.png" alt-text="Azure DevOps Demo Generator project created screen" lightbox="media/projectcreated.png"::: +1. Select the organization where you want to host the project created by the Azure DevOps Demo Generator. If you belong to multiple organizations associated with your credentials, choose the appropriate one. +2. Enter a project name, such as "MyProjectDemo," that you and other contributors can easily identify as a demo project. +3. Choose from several available templates, such as: + - **eShopOnWeb**: a .NET app that deploys to Azure App Service + - **PartsUnlimited**: an ASP.NET app with customized CI/CD pipelines + - **MyShuttle**: a Java app with Azure App Service deployment. + If you're following a lab from [Azure DevOps Labs](https://www.azuredevopslabs.com), select the **DevOps Labs** section to choose the relevant template. -1. Select the link to go to the new demo Azure DevOps Services project and confirm it was successfully provisioned. + Use templates that provide fictional Azure DevOps users, prepopulated Agile work items and data, source code in an Azure Repos Git repo, and access to Azure Pipelines. +4. (Optional) Manually install any required extensions by selecting the provided link for each extension. This link opens the extension's page in the Azure DevOps Marketplace, where you can install it. +5. (Optional) Approve the installation of other required extensions when prompted. If the demo generation process detects missing extensions, consent by pressing **Y** or **Yes**, then press **Enter** to create the 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"::: + Your project might take a few minutes for the Demo Generator to create. -> [!NOTE] -> You must provide your own information such as URLs, logins, password, and others for the configuration of demo endpoints that use Azure resources. + > [!div class="mx-imgBorder"] + > :::image type="content" source="media/104.png" alt-text="Screenshot shows Required extensions setup in organization." lightbox="media/104.png"::: -Next: [Learn how you can build your own template](build-your-own-template.md) - -## Common Issues and workarounds: - -### **Issue:** Error while creating release definition: -Tasks with versions `ARM Outputs:4.*` are not valid for deploy job `Agent job` in stage Stage 1 - -**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 - -------------- - -### **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 - -**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 - -**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 +6. Go to your organization to confirm that the project was created once the "Project created successfully" message displays. diff --git a/docs/dev-resources/index.yml b/docs/dev-resources/index.yml index 2bdd799e8aa..593c480456c 100644 --- a/docs/dev-resources/index.yml +++ b/docs/dev-resources/index.yml @@ -1,16 +1,16 @@ ### YamlMime:Landing title: Developer resources documentation -summary: Use command line tools, REST APIS, and more to interface with Azure DevOps programmatically. +summary: Use command line tools, REST APIS, and more to interface with Azure DevOps programmatically and build applications. metadata: title: Azure DevOps Developer resources documentation titleSuffix: Azure DevOps - description: Use command line interface, REST APIs, typescript tools and more to interface with Azure DevOps . + description: Use command line interface, REST APIs, typescript tools and more to interface with and build on 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 @@ -19,6 +19,30 @@ landingContent: # Cards and links should be based on top customer tasks or top subjects # Start card title with a verb # Card (optional) + - title: Build applications on Azure DevOps + linkLists: + - linkListType: overview + links: + - text: Learn about building applications + url: ../integrate/index.md + - text: Authentication types overview + url: ../integrate/get-started/authentication/authentication-guidance.md + - linkListType: get-started + links: + - text: Authenticate with Entra tokens + url: ../integrate/get-started/authentication/entra.md + - text: Authenticate with OAuth 2.0 + url: ../integrate/get-started/authentication/oauth.md + - text: Authenticate with service principals + url: ../integrate/get-started/authentication/service-principal-managed-identity.md + - text: Authenticate with personal access tokens (PATs) + url: ../organizations/accounts/use-personal-access-tokens-to-authenticate.md + - linkListType: reference + links: + - text: Azure DevOps REST API Reference + url: /rest/api/azure/devops/ + - text: .NET client libraries + url: ../integrate/concepts/dotnet-client-libraries.md - title: Azure DevOps Command Line Interface (CLI) linkLists: - linkListType: get-started @@ -47,27 +71,13 @@ landingContent: linkLists: - linkListType: get-started links: - - text: Cross-platform CLI for Azure DevOps (tfx-cli) - url: ../extend/publish/command-line.md?toc=/azure/devops/dev-resources/toc.json - - title: Azure DevOps REST API Reference - linkLists: - - linkListType: get-started - links: - - text: Get started - url: /rest/api/azure/devops/index - - text: Build - url: /rest/api/azure/devops/build/index - - text: Core - url: /rest/api/azure/devops/core/index - - text: Git - url: /rest/api/azure/devops/git/index - - text: Work item tracking - url: /rest/api/azure/devops/wit/index - - title: Azure DevOps Demo generator + - text: Node CLI for Azure DevOps (tfx-cli) + url: ../extend/publish/command-line.md + - title: Azure DevOps Demo Generator linkLists: - linkListType: get-started links: - - text: About the Demo generator + - text: About the Demo Generator url: ../demo-gen/index.md - - text: Get started - url: ../demo-gen/use-demo-generator-v2.md \ No newline at end of file + - text: Get Started + url: ../demo-gen/use-demo-generator-v2.md diff --git a/docs/dev-resources/toc.yml b/docs/dev-resources/toc.yml index 55df7621aa8..9eb9e7a5cfe 100644 --- a/docs/dev-resources/toc.yml +++ b/docs/dev-resources/toc.yml @@ -1,19 +1,84 @@ - name: Developer resources href: index.yml +- name: Authenticate + items: + - name: Authentication overview + href: ../integrate/get-started/authentication/authentication-guidance.md + - name: Authenticate with Entra tokens + displayName: authenticate, security, Entra + href: ../integrate/get-started/authentication/entra.md + - name: Authenticate with OAuth 2.0 + displayName: authenticate, access, token, app, security + href: ../integrate/get-started/authentication/oauth.md + - name: Authenticate with service principals + displayName: authenticate, access, security, service, principal, managed, identity + href: ../integrate/get-started/authentication/service-principal-managed-identity.md + - name: Authenticate with personal access tokens (PATs) + displayName: authenticate, security, PATs + href: ../organizations/accounts/use-personal-access-tokens-to-authenticate.md +- name: Build with Azure DevOps + items: + - name: Building applications + href: ../integrate/index.md + - name: Get started + items: + - name: Call REST APIs + displayName: integrate, instance, collection + href: ../integrate/how-to/call-rest-api.md + - name: REST API versioning + displayName: applications, services, usage + href: ../integrate/concepts/rest-api-versioning.md + - name: .NET client libraries + displayName: integrate, developer, package, rest, api + href: ../integrate/concepts/dotnet-client-libraries.md + - name: Best practices for building apps + displayName: integrate, procedure, correct, effective + href: ../integrate/concepts/integration-bestpractices.md + - name: Integrate with service hooks + href: ../service-hooks/overview.md?toc=/azure/devops/marketplace-extensibility/toc.json + - name: Develop Marketplace extensions + href: ../marketplace-extensibility/?toc=/azure/devops/marketplace-extensibility/toc.json + - name: Samples + items: + - name: REST API Samples + displayName: PATs, personal, access, token, client, libraries + href: ../integrate/get-started/rest/samples.md + - name: Create a bug + displayName: client, library, code, project, PAT + href: ../integrate/quickstarts/create-bug-quickstart.md + - name: Query work items + displayName: get, fetch, queries, rest, api + href: ../integrate/quickstarts/work-item-quickstart.md + - name: Create a service hooks subscription + displayName: rest, api, build, complete, code + href: ../service-hooks/create-subscription.md + - name: .NET Sample Apps + displayName: sample, c#, library, REST, authenticate + href: ../integrate/get-started/client-libraries/samples.md + - name: .NET (Legacy) Sample Apps + displayName: SOAP, authenticate, PAT, Azure, Visual, Studio + href: ../integrate/get-started/client-libraries/soapSamples.md + - name: Create a PR status server + displayName: pull, request, web, configure, service, hook + href: ../repos/git/create-pr-status-server.md + - name: Use Azure Functions to create custom branch policies + displayName: pull, request, PR, Repos, event, service, hook + href: ../repos/git/create-pr-status-server-with-azure-functions.md - name: Azure DevOps CLI href: ../cli/toc.yml - expanded: true -- name: Git commands - href: ../repos/git/command-prompt.md -- name: TFVC repository commands - href: ../repos/tfvc/use-team-foundation-version-control-commands.md -- name: Test case management commands - href: ../test/test-case-managment-reference.md -- name: Work tracking administration commands - href: ../reference/witadmin/witadmin-customize-and-manage-objects-for-tracking-work.md -- name: Cross-platform CLI for Azure DevOps - href: ../extend/publish/command-line.md -- name: Azure DevOps REST APIs - href: /rest/api/azure/devops/ +- name: Node CLI for Azure DevOps (tfx-cli) + href: ../extend/publish/command-line.md +- name: Reference + items: + - name: Azure DevOps REST API Reference + href: /rest/api/azure/devops/ + - name: Git commands + href: ../repos/git/command-prompt.md + - name: TFVC repository commands + href: ../repos/tfvc/use-team-foundation-version-control-commands.md + - name: Test case management commands + href: ../test/test-case-managment-reference.md + - name: Work tracking administration commands + href: ../reference/witadmin/witadmin-customize-and-manage-objects-for-tracking-work.md - name: Azure DevOps Demo Generator href: ../demo-gen/toc.yml diff --git a/docs/docfx.json b/docs/docfx.json index 0c7bc605615..d8ed76ff4f8 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", @@ -201,12 +212,15 @@ "ms.custom": { "repos/**": "UpdateFrequency3" }, + "ms.update-cycle": { + "repos/**": "1095-days" + }, "recommendations": { "pipelines/repos/**": "true", "repos/tfvc/**": "true", "repos/get-started/**": "true", "repos/git/**": "true" - }, + }, "exclude_monikers": { "reference/error/**/*.md": [ "azure-devops" @@ -214,52 +228,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 +313,8 @@ "reference/index.yml": [ "tfs-2013", "tfs-2015", - "tfs-2017" + "tfs-2017", + "tfs-2018" ], "organizations/security/**/*.md": [ "tfs-2013", @@ -350,12 +375,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 +397,8 @@ "repos/index.yml": [ "tfs-2013", "tfs-2015", - "tfs-2017" + "tfs-2017", + "tfs-2018" ], "repos/get-started/**/*.md": [ "tfs-2013", @@ -380,7 +408,8 @@ "user-guide/**/*.md": [ "tfs-2013", "tfs-2015", - "tfs-2017" + "tfs-2017", + "tfs-2018" ], "user-guide/**/*.yml": [ "tfs-2013", @@ -389,38 +418,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 +464,8 @@ ], "test/**/*.md": [ "tfs-2015", - "tfs-2017" + "tfs-2017", + "tfs-2018" ], "test/**/*.yml": [ "tfs-2015", @@ -437,33 +474,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..175620a3514 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: 06/06/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,214 @@ 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). +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 - tfx extension publish --manifest-globs your-manifest.json --share-with yourOrganization - ``` +```powershell +tfx extension publish --manifest-globs your-manifest.json --share-with yourOrganization +``` ### 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 +626,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 +712,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 +746,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 +760,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 deleted file mode 100644 index 836b715daf2..00000000000 --- a/docs/extend/develop/add-chart.md +++ /dev/null @@ -1,352 +0,0 @@ ---- -ms.subservice: azure-devops-ecosystem -title: Add a chart | Extensions for Azure DevOps Services -description: Add a chart to your extension in Azure DevOps Services -ms.assetid: ff6b9bbf-fb57-469b-8191-922660393a21 -ms.topic: conceptual -ms.author: chcomley -author: chcomley -ms.date: 12/31/2019 -monikerRange: '>= azure-devops-2019' ---- - -# Add a chart - -[!INCLUDE [version-gt-eq-2019](../../includes/version-gt-eq-2019.md)] - -Learn how you can add charts to your extensions. Charts can be added to any Azure DevOps Services extension. - -[!INCLUDE [extension-docs-new-sdk](../../includes/extension-docs-new-sdk.md)] - -Charts are easy to create, resizable, interactive, and consistent with the Azure DevOps Services look and feel. -The following chart types are supported: - -- Line -- Bar -- Column -- Area -- Stacked bar -- Stacked column -- Stacked area -- Pie -- Pivot table -- Histogram - -If you're in a hurry and want to get your hands on the code right away, you can download the [complete samples](https://github.com/Microsoft/azure-devops-extension-sample). -Once downloaded, go to the `charts` folder, and then follow [the packaging and publishing instructions](../publish/overview.md) to publish the sample extension. -The extension contains sample chart widgets. - -## How to organize your code - -For this tutorial, we create a widget and add a chart to it. -To do so, in the `home` folder for your project, create a `chart.html` file with the following contents: - -### HTML file -```html - - - - - - - -

-

Chart Widget

-
-
- - -``` -> Use the **npm install** command to retrieve the SDK: `npm install vss-web-extension-sdk`. To learn more about the SDK, visit the [Client SDK GitHub Page](https://github.com/Microsoft/vss-sdk). - -Ensure that the `VSS.SDK.js` file is inside the `sdk/scripts` folder so that the path is `home/sdk/scripts/VSS.SDK.js`. - -### Images -Add images to an `img` folder in your project directory so that the path is `home/img/logo.png` and `home/img/CatalogIcon.png`. -See our newest documentation, the [Formula Design System](https://developer.microsoft.com/en-us/azure-devops/) and [Azure DevOps extension sample SDK](https://github.com/microsoft/azure-devops-extension-sample/tree/master/static). - -### Extension manifest file -In the `home` folder of your project, create your [extension manifest file](../develop/manifest.md). Create a `vss-extension.json` file with the following contents: - -```json -{ - "manifestVersion": 1, - "id": "samples-charts", - "version": "1.0.0", - "name": "Interactive Charts in Azure DevOps Services", - "description": "Samples of interactive charts from the Chart SDK.", - "publisher": "Fabrikam", - "targets": [ - { - "id": "Microsoft.VisualStudio.Services" - } - ], - "icons": { - "default": "img/logo.png" - }, - "demands": ["contribution/ms.vss-dashboards-web.widget-sdk-version-2", "contribution/ms.vss-web.charts-service"], - "contributions": [ - { - "id": "chart", - "type": "ms.vss-dashboards-web.widget", - "targets": [ - "ms.vss-dashboards-web.widget-catalog" - ], - "properties": { - "name": "Sample Chart", - "description": "A simple chart widget with no configuration and hard-coded data.", - "catalogIconUrl": "img/CatalogIcon.png", - "uri": "chart.html", - "supportedSizes": [ - { - "rowSpan": 2, - "columnSpan": 2 - } - ], - "supportedScopes": [ - "project_team" - ] - } - } - ], - "files": [ - { - "path": "chart.html", - "addressable": true - }, - { - "path": "sdk/scripts/VSS.SDK.js", - "addressable": true - }, - { - "path": "img", - "addressable": true - }, - { - "path": "scripts", - "addressable": true - } - ], - "scopes": [ - ] -} -``` - -Before uploading this extension, you must update the `publisher` to yours. - -Put the following code snippets into a `chart.js` file in a `scripts` folder, so that the path is `home/scripts/chart.js`. -Then, follow [the packaging and publishing instructions](../publish/overview.md) to publish your extension. - -## Charts - -### Chart - -This sample renders a chart. The `data` and `labelValues` have been hardcoded here, and would need to be changed to the data you want to visualize. - -```JavaScript -VSS.init({ - explicitNotifyLoaded: true, - usePlatformStyles: true - }); - -VSS.require([ - "TFS/Dashboards/WidgetHelpers", - "Charts/Services" - ], - function (WidgetHelpers, Services) { - WidgetHelpers.IncludeWidgetStyles(); - VSS.register("chart", function () { - return { - load:function() { - return Services.ChartsService.getService().then(function(chartService){ - var $container = $('#Chart-Container'); - var chartOptions = { - "hostOptions": { - "height": "290", - "width": "300" - }, - "chartType": "pie", - "series": [{ - "data": [11, 4, 3, 1] - }], - "xAxis": { - "labelValues": ["Design", "On Deck", "Completed", "Development"] - }, - "specializedOptions": { - "showLabels": "true", - "size": 200 - } - }; - - chartService.createChart($container, chartOptions); - return WidgetHelpers.WidgetStatusHelper.Success(); - }); - } - } - }); - VSS.notifyLoadSucceeded(); -}); -``` - -Here, the chart's size is defined in `hostOptions`. The series property is an array and contains a single object with data in it. The `xAxis` object contains `labelValues`, which correspond to the `data`. -For pie charts, we also have some special options that are defined by the `specializedOptions` property. Here, we're explicitly enabling data labels for the pie chart. -We also need to set the size of the pie chart by specifying its outer diameter. - -The chart requires a container, the chart options, and a call to the Chart Service to initialize and render. For more information on chart options, see [vss-web-extension-sdk/typings/charts](https://github.com/Microsoft/vss-web-extension-sdk/blob/master/typings/charts.d.ts). - -### Stacked area chart - -The following sample renders a stacked area chart. This chart type is ideal to compare a relationship of parts to a whole and highlight general trends across categories. It's commonly used to compare trends over time. -This sample also specifies a custom color for one of the series being rendered. - -```JavaScript -VSS.init({ - explicitNotifyLoaded: true, - usePlatformStyles: true - }); - -VSS.require([ - "TFS/Dashboards/WidgetHelpers", - "Charts/Services" - ], - function (WidgetHelpers, Services) { - WidgetHelpers.IncludeWidgetStyles(); - VSS.register("StackedAreaChart", function () { - return { - load:function() { - return Services.ChartsService.getService().then(function(chartService){ - var $container = $('#Chart-Container'); - var chartOptions = { - "hostOptions": { - "height": "290", - "width": "300" - }, - "chartType": "stackedArea", - "series": [ - { - "name": "Completed", - "data": [1,3,4,3,6,1,9,0,8,11] - }, - { - "name": "Development", - "data": [1,1,0,3,0,2,8,9,2,8] - }, - { - "name": "Design", - "data": [0,0,0,6,1,1,9,9,1,9], - "color": "#207752" - }, - { - "name": "On Deck", - "data": [1,2,4,5,4,2,1,7,0,6] - } - ], - "xAxis": { - "labelFormatMode": "dateTime_DayInMonth", - "labelValues": [ - "1/1/2016", - "1/2/2016", - "1/3/2016", - "1/4/2016", - "1/5/2016", - "1/6/2016", - "1/7/2016", - "1/8/2016", - "1/9/2016", - "1/10/2016" - ] - } - } - chartService.createChart($container, chartOptions); - return WidgetHelpers.WidgetStatusHelper.Success(); - }); - } - } - }); - VSS.notifyLoadSucceeded(); -}); -``` - -### Pivot table - -This sample renders a Pivot Table. This chart type helps arrange and summarize complex data in a tabular form. - -```JavaScript -VSS.init({ - explicitNotifyLoaded: true, - usePlatformStyles: true - }); - -VSS.require([ - "TFS/Dashboards/WidgetHelpers", - "Charts/Services" - ], - function (WidgetHelpers, Services) { - WidgetHelpers.IncludeWidgetStyles(); - VSS.register("PivotTable", function () { - return { - load:function() { - return Services.ChartsService.getService().then(function(chartService){ - var $container = $('#Chart-Container'); - var chartOptions = { - "hostOptions": { - "height": "290", - "width": "300" - }, - "chartType": "table", - "xAxis": { - "labelValues": ["Design","In Progress","Resolved","Total"] - }, - "yAxis": { - "labelValues": ["P1","P2","P3","Total"] - }, - "series": [ - { - "name": "Design", - "data": [ - [0,0,1], - [0,1,2], - [0,2,3] - ] - }, - { - "name": "In Progress", - "data": [ - [1,0,4], - [1,1,5], - [1,2,6] - ] - }, - { - "name": "Resolved", - "data": [ - [2,0,7], - [2,1,8], - [2,2,9] - ] - }, - { - "name": "Total", - "data": [ - [3,0,12], - [3,1,15], - [3,2,18], - [0,3,6], - [1,3,15], - [2,3,24], - [3,3,10] - ], - "color": "rgba(255,255,255,0)" - } - ] - } - - chartService.createChart($container, chartOptions); - return WidgetHelpers.WidgetStatusHelper.Success(); - }); - } - } - }); - VSS.notifyLoadSucceeded(); -}); -``` diff --git a/docs/extend/develop/add-dashboard-widget.md b/docs/extend/develop/add-dashboard-widget.md index 0552703a78c..2c003b1faca 100644 --- a/docs/extend/develop/add-dashboard-widget.md +++ b/docs/extend/develop/add-dashboard-widget.md @@ -1,404 +1,335 @@ --- -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 +ai-usage: ai-assisted +ms.topic: concept-article ms.author: chcomley author: chcomley -ms.date: 10/31/2019 -monikerRange: '>= azure-devops-2019' +ms.date: 07/02/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 -To create extensions for Azure DevOps or TFS, there are some prerequisite software and tools you'll need: +| Requirement | Description | +|-------------|-------------| +| **Programming knowledge** | JavaScript, HTML, and CSS knowledge for widget development | +| **Azure DevOps organization** | [Create an organization](../../organizations/accounts/create-organization.md) | +| **Text editor** | We use [Visual Studio Code](https://code.visualstudio.com/) for tutorials | +| **Node.js** | [Latest version of Node.js](https://nodejs.org) | +| **Cross-platform CLI** | [tfx-cli](https://github.com/microsoft/tfs-cli) to package extensions
Install using: `npm i -g tfx-cli` | +| **Project directory** | Home directory with this structure after completing the tutorial:

`|--- README.md`
`|--- sdk`
` |--- node_modules`
` |--- scripts`
` |--- VSS.SDK.min.js`
`|--- img`
` |--- logo.png`
`|--- scripts`
`|--- hello-world.html // html page for your widget`
`|--- vss-extension.json // extension manifest` | -**Knowledge:** -Some knowledge of JavaScript, HTML, CSS is required for widget development. +## Tutorial overview -- 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. +This tutorial teaches widget development through three progressive examples: -**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 +| Part | Focus | What you learn | +|------|-------|-------------------| +| [Part 1: Hello World](#part-1) | Basic widget creation | Create a widget that displays text | +| [Part 2: REST API integration](#part-2) | Azure DevOps API calls | Add REST API functionality to fetch and display data | +| [Part 3: Widget configuration](#part-3) | User customization | Implement configuration options for your widget | -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. +> [!TIP] +> **Skip the tutorial:** Download the complete [sample extension](https://github.com/Microsoft/azure-devops-extension-sample), go to the `widgets` folder, and jump to [Step 6](#package-publish-share) to publish three ready-to-use example widgets. -> [!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). -> 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. +Before you begin, review the [basic widget styles](./styles-from-widget-sdk.md) and structural guidance we provide. -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. - - + ## Part 1: Hello World -This part presents a widget that prints "Hello World" using JavaScript. - -![Overview dashboard with a sample widget](../media/add-dashboard-widget/sample.png) +Create a basic widget that displays "Hello World" using JavaScript. This foundation demonstrates the core widget development concepts. -### Step 1: Get the client SDK - `VSS.SDK.min.js` +:::image type="content" source="../media/add-dashboard-widget/sample.png" alt-text="Screenshot of Overview dashboard with a sample widget."::: -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. +### Step 1: Install the client SDK -Use the 'npm install' command to retrieve the SDK: +The VSS SDK enables your widget to communicate with Azure DevOps. Install it using npm: -```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). +Copy the `VSS.SDK.min.js` file from `vss-web-extension-sdk/lib` to your `home/sdk/scripts` folder. -### Step 2: Your HTML page - `hello-world.html` +For more SDK documentation, see the [Client SDK GitHub page](https://github.com/Microsoft/vss-sdk). -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. +### Step 2: Create the HTML structure -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. +Create `hello-world.html` in your project directory. This file provides the widget's layout and references to required scripts. ```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. +Widgets run in iframes, so most HTML head elements except ` + 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`. +#### Key JavaScript components -`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. +| Function | Purpose | +|----------|---------| +| `VSS.init()` | Initializes communication between widget and Azure DevOps | +| `VSS.require()` | Loads required SDK libraries and widget helpers | +| `VSS.register()` | Registers your widget with a unique identifier | +| `WidgetHelpers.IncludeWidgetStyles()` | Applies default Azure DevOps styling | +| `VSS.notifyLoadSucceeded()` | Notifies the framework that loading completed successfully | -`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. +> [!IMPORTANT] +> The widget name in `VSS.register()` must match the `id` in your extension manifest (Step 5). -`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. +### Step 4: Add extension images +Create the required images for your extension: -> [!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. - -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. - - - -### Step 4: Your extension's logo: logo.png - -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. +- **Extension logo**: 98x98 pixel image named `logo.png` in the `img` folder +- **Widget catalog icon**: 98x98 pixel image named `CatalogIcon.png` in the `img` folder +- **Widget preview**: 330x160 pixel image named `preview.png` in the `img` folder -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. +These images display in the Marketplace and widget catalog when users browse available extensions. -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: Create the extension manifest -### 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: +Create `vss-extension.json` in your project's root directory. This file defines your extension's metadata and contributions: ```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) - -> [!NOTE] -> The **publisher** here needs to be changed to your publisher name. To create a publisher now, visit [Package/Publish/Install](../publish/overview.md). - -#### Icons +> [!IMPORTANT] +> Replace `"publisher": "fabrikam"` with your actual publisher name. Learn how to [create a publisher](../publish/overview.md). -The **icons** stanza specifies the path to your extension's icon in your manifest. +#### Essential manifest properties -#### Contributions +| Section | Purpose | +|---------|---------| +| **Basic info** | Extension name, version, description, and publisher | +| **Icons** | Paths to your extension's visual assets | +| **Contributions** | Widget definitions including ID, type, and properties | +| **Files** | All files to include in the extension package | -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. +For complete manifest documentation, see [Extension manifest reference](manifest.md). + -| 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. | +### Step 6: Package and publish your extension +Package your extension and publish it to the Visual Studio Marketplace. -#### Files +#### Install the packaging tool -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). - - - -### 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. - -#### 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. - -```no-highlight +```cmd npm i -g tfx-cli ``` - -#### Package your extension + + +#### Create your extension package -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. +From your project directory, run: -```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. +This action creates a `.vsix` file that contains your packaged extension. -After you have your packaged extension in a .vsix file, you're ready to publish your extension to the Marketplace. +#### Set up a publisher -#### Create publisher for the extension +1. Go to the [Visual Studio Marketplace Publishing Portal](https://marketplace.visualstudio.com/manage/createpublisher). +2. Sign in and create a publisher if you don't have one. +3. Choose a unique publisher identifier (used in your manifest file). +4. Update your `vss-extension.json` to use your publisher name instead of "fabrikam." -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. +#### Upload your extension -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` - * 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** +1. In the Publishing Portal, select **Upload new extension**. +2. Choose your `.vsix` file and upload it. +3. Share the extension with your Azure DevOps organization. -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. +Alternatively, use the command line: -**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 +```cmd +tfx extension publish --manifest-globs vss-extension.json --share-with yourOrganization +``` -After creating a publisher, you can now upload your extension to the Marketplace. +> [!TIP] +> Use `--rev-version` to automatically increment the version number when updating an existing extension. -1. Find the Upload new extension button, navigate 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. +### Step 7: Install and test your widget -```no-highlight -tfx extension publish --manifest-globs your-manifest.json --share-with yourOrganization -``` +To test, add your widget to a dashboard: - +1. Go to your Azure DevOps project: `https://dev.azure.com/{Your_Organization}/{Your_Project}`. +2. Go to **Overview** > **Dashboards**. +3. Select **Add a widget**. +4. Find your widget in the catalog and select **Add**. -### Step 7: Add widget from the catalog +Your "Hello World" widget appears on the dashboard, displaying the text you configured. -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**. - - The widget appears on your dashboard. +**Next step**: Continue to [Part 2](#part-2) to learn how to integrate Azure DevOps REST APIs into your widget. - + ## 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. +Extend your widget to interact with Azure DevOps data using REST APIs. This example demonstrates how to fetch query information and display it dynamically in your widget. -![Overview dashboard with a sample widget using the REST API for WorkItemTracking.](../media/add-dashboard-widget/sample2.png) +In this part, use the [Work Item Tracking REST API](/rest/api/azure/devops/) to retrieve information about an existing query and display the query details below 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: Create the enhanced HTML file -```no-highlight +Create a new widget file that builds on the previous example. Copy `hello-world.html` and rename it to `hello-world2.html`. Your project structure now includes: + +``` |--- 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 -|--- hello-world2.html // renamed copy of hello-world.html -|--- vss-extension.json // extension's manifest +|--- node_modules +|--- sdk/ + |--- scripts/ + |--- VSS.SDK.min.js +|--- img/ + |--- logo.png +|--- scripts/ +|--- hello-world.html // Part 1 widget +|--- hello-world2.html // Part 2 widget (new) +|--- vss-extension.json // Extension 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. +#### Update the widget HTML structure + +Make these changes to `hello-world2.html`: + +1. **Add a container for query data**: Include a new `
` element to display query information. +2. **Update the widget identifier**: Change the widget name from `HelloWorldWidget` to `HelloWorldWidget2` for unique identification. ```html - - + + @@ -421,52 +352,60 @@ This allows the framework to uniquely identify the widget within the extension. ``` -### Step 2: Access Azure DevOps resources +### Step 2: Configure API access permissions -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. +Before making REST API calls, configure the required permissions in your extension manifest. + +#### Add the work scope + +The `vso.work` scope grants read-only access to work items and queries. Add this scope to your `vss-extension.json`: ```json { - ..., - "scopes":[ + "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". +#### Complete manifest example + +For a complete manifest with other properties, structure it like this: + +```json +{ + "name": "example-widget", + "publisher": "example-publisher", + "version": "1.0.0", + "scopes": [ + "vso.work" + ] +} +``` -### Step 3: Make the REST API Call +> [!IMPORTANT] +> **Scope limitations**: Adding or changing scopes after publishing isn't supported. If you already published your extension, you must remove it from the Marketplace first. Go to the [Visual Studio Marketplace Publishing Portal](https://marketplace.visualstudio.com/manage/createpublisher), find your extension, and select **Remove**. -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. +### Step 3: Implement REST API integration -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`. +Azure DevOps provides JavaScript REST client libraries through the SDK. These libraries wrap AJAX calls and map API responses to usable objects. -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. +#### Update the widget JavaScript -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: +Replace the `VSS.require` call in your `hello-world2.html` to include the Work Item Tracking REST client: -```JavaScript -VSS.require(["TFS/Dashboards/WidgetHelpers", "TFS/WorkItemTracking/RestClient"], - function (WidgetHelpers, TFS_Wit_WebApi) { +```js +VSS.require(["AzureDevOps/Dashboards/WidgetHelpers", "AzureDevOps/WorkItemTracking/RestClient"], + function (WidgetHelpers, WorkItemTrackingRestClient) { WidgetHelpers.IncludeWidgetStyles(); VSS.register("HelloWorldWidget2", function () { var projectId = VSS.getWebContext().project.id; var getQueryInfo = function (widgetSettings) { // Get a WIT client to make REST calls to Azure DevOps Services - return TFS_Wit_WebApi.getClient().getQuery(projectId, "Shared Queries/Feedback") + return WorkItemTrackingRestClient.getClient().getQuery(projectId, "Shared Queries/Feedback") .then(function (query) { - // Do something with the query + // Process query data (implemented in Step 4) return WidgetHelpers.WidgetStatusHelper.Success(); }, function (error) { @@ -487,32 +426,45 @@ 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. +#### Key implementation details -### Step 4: Display the Response +| Component | Purpose | +|-----------|---------| +| `WorkItemTrackingRestClient.getClient()` | Gets an instance of the Work Item Tracking REST client | +| `getQuery()` | Retrieves query information wrapped in a promise | +| `WidgetStatusHelper.Failure()` | Provides consistent error handling for widget failures | +| `projectId` | Current project context required for API calls | -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: +> [!TIP] +> **Custom query paths**: If you don't have a "Feedback" query in "Shared Queries", replace `"Shared Queries/Feedback"` with the path to any query that exists in your project. -```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: "" ) ) ); +### Step 4: Display API response data - // Append the list to the query-info-container - var $container = $('#query-info-container'); - $container.empty(); - $container.append($list); +Render the query information in your widget by processing the REST API response. + +#### Add query data rendering + +Replace the `// Process query data` comment with this implementation: + +```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: +The `getQuery()` method returns a `Contracts.QueryHierarchyItem` object with properties for query metadata. This example displays three key pieces of information below the "Hello World" text. + +#### Complete working example + +Your final `hello-world2.html` file should look like this: ```html @@ -525,21 +477,21 @@ Your final `hello-world2.html` is as follows: usePlatformStyles: true }); - VSS.require(["TFS/Dashboards/WidgetHelpers", "TFS/WorkItemTracking/RestClient"], - function (WidgetHelpers, TFS_Wit_WebApi) { + VSS.require(["AzureDevOps/Dashboards/WidgetHelpers", "AzureDevOps/WorkItemTracking/RestClient"], + function (WidgetHelpers, WorkItemTrackingRestClient) { WidgetHelpers.IncludeWidgetStyles(); VSS.register("HelloWorldWidget2", function () { var projectId = VSS.getWebContext().project.id; var getQueryInfo = function (widgetSettings) { // Get a WIT client to make REST calls to Azure DevOps Services - return TFS_Wit_WebApi.getClient().getQuery(projectId, "Shared Queries/Feedback") + return WorkItemTrackingRestClient.getClient().getQuery(projectId, "Shared Queries/Feedback") .then(function (query) { // 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: "") )); + $list.append($('
      • ').text("Created By: " + (query.createdBy ? query.createdBy.displayName : ""))); // Append the list to the query-info-container var $container = $('#query-info-container'); @@ -578,287 +530,302 @@ Your final `hello-world2.html` is as follows: ``` - + + +### Step 5: Update the extension manifest -### Step 5: Extension Manifest Updates +To make it available in the widget catalog, add your new widget to the 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. +#### Add the second widget contribution + +Update `vss-extension.json` to include your REST API-enabled widget. Add this contribution to the `contributions` array: ```json - { - ..., - "contributions":[ - ..., +{ + "contributions": [ + // ...existing HelloWorldWidget contribution..., { - "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"] - } - } + "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" + ] +} +``` - ], - "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" - ] - } - ``` +> [!TIP] +> **Preview image**: Create a `preview2.png` image (330x160 pixels) and place it in the `img` folder to show users what your widget looks like in the catalog. + +### Step 6: Package, publish, and share + +[Package, publish, and share your extension](#package-publish-share). If you already published the extension, you can repackage and update it directly in the Marketplace. + +### Step 7: Test your REST API widget + +To view the REST API integration in action, add the new widget to your dashboard: + +1. Go to your Azure DevOps project: `https://dev.azure.com/{Your_Organization}/{Your_Project}`. +2. Select **Overview** > **Dashboards**. +3. Select **Add a widget**. +4. Find "Hello World Widget 2 (with API)" and select **Add**. -### Step 6: Package, Publish, and Share +Your enhanced widget displays both the "Hello World" text and live query information from your Azure DevOps project. -[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. +**Next steps**: Continue to [Part 3](#part-3) to add configuration options that let users customize which query to display. + -### Step 7: Add Widget From the Catalog +## Part 3: Configure Hello World -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. +Build on [Part 2](#part-2) by adding user configuration capabilities to your widget. Instead of hard-coding the query path, create a configuration interface that lets users select which query to display, with live preview functionality. - +This part demonstrates how to create configurable widgets that users can customize to their specific needs while providing real-time feedback during configuration. -## Part 3: Hello World with Configuration +:::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."::: -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. -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**. +### Step 1: Create configuration files -![Overview dashboard live preview of the widget based on changes.](../media/add-dashboard-widget/sampleConfiguration.png) +Widget configurations share many similarities with widgets themselves—both use the same SDK, HTML structure, and JavaScript patterns, but serve different purposes within the extension framework. -### Step 1: HTML +#### Set up the project structure -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. +To support widget configuration, create two new files: -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: +1. Copy `hello-world2.html` and rename it to `hello-world3.html`, your configurable widget. +2. Create a new file called `configuration.html`, which handles the configuration interface. -```no-highlight +Your project structure now includes: + +``` |--- README.md -|--- sdk +|--- sdk/ |--- node_modules - |--- scripts + |--- scripts/ |--- VSS.SDK.min.js -|--- img +|--- img/ |--- logo.png -|--- scripts -|--- configuration.html -|--- hello-world.html // html page to be used for your widget -|--- hello-world2.html // renamed copy of hello-world.html -|--- hello-world3.html // renamed copy of hello-world2.html -|--- vss-extension.json // extension's manifest +|--- scripts/ +|--- configuration.html // New: Configuration interface +|--- hello-world.html // Part 1: Basic widget +|--- hello-world2.html // Part 2: REST API widget +|--- hello-world3.html // Part 3: Configurable widget (new) +|--- vss-extension.json // Extension 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. +#### Create the configuration interface + +Add this HTML structure to `configuration.html`, which creates a dropdown selector for choosing queries: ```html - - - - - - -
        -
        - - -
        -
        - - + + + + + + +
        +
        + + +
        +
        + + ``` -### Step 2: JavaScript - Configuration +### Step 2: Implement configuration 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. - -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. - -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). - -### Step 3: JavaScript - Enable Live Preview - -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. - -Add the below in the function assigned to the `load` property. - -```JavaScript - $queryDropdown.on("change", function () { - var customSettings = { - data: JSON.stringify({ - queryPath: $queryDropdown.val() - }) - }; - var eventName = WidgetHelpers.WidgetEvent.ConfigurationChange; - var eventArgs = WidgetHelpers.WidgetEvent.Args(customSettings); - widgetConfigurationContext.notify(eventName, eventArgs); - }); -``` +#### Configuration contract details -> You need to notify the framework of configuration change at least once so that the "Save" button can be enabled. +The `IWidgetConfiguration` contract requires these key functions: -At the end, your `configuration.html` looks like this: +| Function | Purpose | When called | +|----------|---------|-------------| +| `load()` | Initialize configuration UI with existing settings | When configuration dialog opens | +| `onSave()` | Serialize user input and validate settings | When user selects **Save** | +> [!TIP] +> **Data serialization**: This example uses JSON to serialize settings. The widget accesses these settings via `widgetSettings.customSettings.data` and must deserialize them accordingly. -```html - - - - - + - - -
        -
        - - -
        -
        - - + VSS.notifyLoadSucceeded(); + }); + + + +
        +
        + + +
        +
        + + ``` -         +> [!IMPORTANT] +> **Enable Save button**: The framework requires at least one configuration change notification to enable the **Save** button. The change event handler ensures this action occurs when users select an option. -### Step 4: JavaScript - Implement reload in the widget + -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. +### Step 4: Make the widget configurable -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. +Transform your widget from Part 2 to use configuration data instead of hard-coded values. This step requires implementing the `IConfigurableWidget` contract. -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. +#### Update widget registration + +In `hello-world3.html`, make these changes: + +1. **Update widget ID**: Change from `HelloWorldWidget2` to `HelloWorldWidget3`. +2. **Add reload function**: Implement the `IConfigurableWidget` contract. ```JavaScript return { @@ -875,43 +842,384 @@ 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. +#### Handle configuration data + +Update the `getQueryInfo` function to use configuration settings instead of hard-coded query paths: ```JavaScript var settings = JSON.parse(widgetSettings.customSettings.data); if (!settings || !settings.queryPath) { var $container = $('#query-info-container'); $container.empty(); - $container.text("Sorry nothing to show, please configure a query path."); + $container.text("Please configure a query path to display data."); 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. +#### Widget lifecycle differences + +| Function | Purpose | Usage guidelines | +|----------|---------|------------------| +| `load()` | Initial widget rendering and one-time setup | Heavy operations, resource initialization | +| `reload()` | Update widget with new configuration | Lightweight updates, data refresh | + +> [!TIP] +> **Performance optimization**: Use `load()` for expensive operations that only need to run once, and `reload()` for quick updates when configuration changes. + +### (Optional) Add a lightbox for detailed information +Dashboard widgets have limited space, making it challenging to display comprehensive information. A lightbox provides an elegant solution by showing detailed data in a modal overlay without navigating away from the dashboard. -### 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. -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. +#### Why use a lightbox in widgets? + +| Benefit | Description | +|---------|-------------| +| **Space efficiency** | Keep widget compact while offering detailed views | +| **User experience** | Maintain dashboard context while showing more information | +| **Progressive disclosure** | Show summary data in widget, details on demand | +| **Responsive design** | Adapt to different screen sizes and widget configurations | + +#### Implement clickable elements + +Update your query data rendering to include clickable elements that trigger the lightbox: + +```JavaScript +// Create a list with clickable 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 : "")); + +// Add a clickable element to open detailed view +var $detailsLink = $(''); +$detailsLink.on('click', function() { + showQueryDetails(query); +}); + +// Append to the container +var $container = $('#query-info-container'); +$container.empty(); +$container.append($list); +$container.append($detailsLink); +``` + +#### Create the lightbox functionality + +Add this lightbox implementation to your widget JavaScript: + +```JavaScript +function showQueryDetails(query) { + // Create lightbox overlay + var $overlay = $('
          '); + var $lightbox = $('
          '); + + // Add close button + var $closeBtn = $(''); + $closeBtn.on('click', function() { + $overlay.remove(); + }); + + // Create detailed content + var $content = $('
          '); + $content.append($('

          ').text(query.name || 'Query Details')); + $content.append($('

          ').html('ID: ' + query.id)); + $content.append($('

          ').html('Path: ' + query.path)); + $content.append($('

          ').html('Created: ' + (query.createdDate ? new Date(query.createdDate).toLocaleDateString() : 'Unknown'))); + $content.append($('

          ').html('Modified: ' + (query.lastModifiedDate ? new Date(query.lastModifiedDate).toLocaleDateString() : 'Unknown'))); + $content.append($('

          ').html('Created By: ' + (query.createdBy ? query.createdBy.displayName : 'Unknown'))); + $content.append($('

          ').html('Modified By: ' + (query.lastModifiedBy ? query.lastModifiedBy.displayName : 'Unknown'))); + + if (query.queryType) { + $content.append($('

          ').html('Type: ' + query.queryType)); + } + + // Assemble lightbox + $lightbox.append($closeBtn); + $lightbox.append($content); + $overlay.append($lightbox); + + // Add to document and show + $('body').append($overlay); + + // Close on overlay click + $overlay.on('click', function(e) { + if (e.target === $overlay[0]) { + $overlay.remove(); + } + }); + + // Close on Escape key + $(document).on('keydown.lightbox', function(e) { + if (e.keyCode === 27) { // Escape key + $overlay.remove(); + $(document).off('keydown.lightbox'); + } + }); +} +``` + +#### Add lightbox styling + +Include CSS styles for the lightbox in your widget HTML `` section: + +```html + +``` + +#### Enhanced widget implementation + +Your complete enhanced widget with lightbox functionality: + +```html + + + + + + + + +

          +

          +
          +
          + + +``` + +**Accessibility considerations**: Ensure your lightbox is keyboard accessible and includes proper labels for screen readers. Test with Azure DevOps' built-in accessibility features. + +> [!IMPORTANT] +> **Performance**: Lightboxes should load quickly. Consider lazy-loading detailed data only when the lightbox opens, rather than fetching everything upfront. + +### Step 5: Configure the extension manifest + +Register both the configurable widget and its configuration interface in your extension manifest. + +#### Add widget and configuration contributions + +Update `vss-extension.json` to include two new contributions: ```json { - ... "contributions": [ - ... , + // ...existing contributions..., { "id": "HelloWorldWidget3", "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)", @@ -939,89 +1247,101 @@ Update the array in the `files` property to include the two new HTML files we ha } ], "files": [ - { - "path": "hello-world.html", "addressable": true - }, - { - "path": "hello-world2.html", "addressable": true - }, - { - "path": "hello-world3.html", "addressable": true - }, - { - "path": "configuration.html", "addressable": true - }, - { - "path": "sdk/scripts", "addressable": true - }, - { - "path": "img", "addressable": true - } - ], - ... + { + "path": "hello-world.html", "addressable": true + }, + { + "path": "hello-world2.html", "addressable": true + }, + { + "path": "hello-world3.html", "addressable": true + }, + { + "path": "configuration.html", "addressable": true + }, + { + "path": "sdk/scripts", "addressable": true + }, + { + "path": "img", "addressable": true + } + ] } ``` -
          -Note the contribution for widget configuration follows a slightly different model than the widget itself. -A contribution entry for widget configuration has: +#### Configuration contribution requirements + +| Property | Purpose | Required value | +|----------|---------|----------------| +| `type` | Identifies contribution as widget configuration | `ms.vss-dashboards-web.widget-configuration` | +| `targets` | Where configuration appears | `ms.vss-dashboards-web.widget-configuration` | +| `uri` | Path to configuration HTML file | Your configuration file path | + +#### Widget targeting pattern + +For configurable widgets, the `targets` array must include a reference to the configuration: + +``` +.. +``` + +> [!WARNING] +> **Configuration button visibility**: If the widget doesn't properly target its configuration contribution, the **Configure** button doesn't appear. Verify the publisher and extension names match your manifest exactly. + +### Step 6: Package, publish, and share + +Deploy your enhanced extension with configuration capabilities. + +If it's your first publication, follow [Step 6: Package, publish, and share](#package-publish-share). For existing extensions, repackage and update directly in the Marketplace. + +### Step 7: Test the configurable widget -- 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. +Experience the full configuration workflow by adding and configuring your widget. -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`. +#### Add the widget to your dashboard -> [!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. +1. Go to `https://dev.azure.com/{Your_Organization}/{Your_Project}`. +2. Go to **Overview** > **Dashboards**. +3. Select **Add a widget**. +4. Find "Hello World Widget 3 (with config)" and select **Add**. -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). +A configuration prompt displays since the widget requires setup: -### Step 6: Package, Publish, and Share +:::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."::: -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. +#### Configure the widget -### 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. +Access configuration through either method: -You would see a message asking you to configure the widget. +- **Widget menu**: Hover over the widget, select the ellipsis (⋯), then **Configure** +- **Dashboard edit mode**: Select **Edit** on the dashboard, then the configure button on the widget -![Overview dashboard with a sample widget from the catalog.](../media/add-dashboard-widget/sampleWidgetWithNoSettings.png) +The configuration panel opens with a live preview in the center. Select a query from the dropdown to see immediate updates, then select **Save** to apply your changes. -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. -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. +### Step 8: Add advanced configuration options +Extend your widget with more built-in configuration features like custom names and sizes. -### 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. +#### Enable name and size configuration -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. -To allow such configuration, add `isNameConfigurable:true` in the properties section for your widget in the extension manifest. +Azure DevOps provides two configurable features out-of-the-box: -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. +| Feature | Manifest property | Purpose | +|---------|------------------|---------| +| **Custom names** | `isNameConfigurable: true` | Users can override the default widget name | +| **Multiple sizes** | Multiple `supportedSizes` entries | Users can resize widgets | + +#### Enhanced manifest example -The extension manifest for the third sample in this guide would look like the below if we enable the widget name and size configuration: ```json { - ... "contributions": [ - ... , { "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)", @@ -1041,40 +1361,26 @@ The extension manifest for the third sample in this guide would look like the be ], "supportedScopes": ["project_team"] } - }, - ... + } + ] } ``` -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)). -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. +#### Display configured names -> [!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. - -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". - -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. -The final return statement in `hello-world3.html` is as follows: +To show custom widget names, update your widget to use `widgetSettings.name`: ```JavaScript return { load: function (widgetSettings) { - // Set your title + // Display configured name instead of hard-coded text var $title = $('h2.title'); $title.text(widgetSettings.name); return getQueryInfo(widgetSettings); }, reload: function (widgetSettings) { - // Set your title + // Update name during configuration changes var $title = $('h2.title'); $title.text(widgetSettings.name); @@ -1083,5 +1389,12 @@ 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. +After you update your extension, you can configure both the widget name and size: + +:::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."::: + +[Repackage](#package-the-extension) and [update](../publish/overview.md) your extension to enable these advanced configuration options. + +**Congratulations!** You created a complete, configurable Azure DevOps dashboard widget with live preview capabilities and user customization options. + 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..77763584920 100644 --- a/docs/extend/develop/auth.md +++ b/docs/extend/develop/auth.md @@ -1,50 +1,54 @@ --- 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 +ms.custom: sfi-image-nochange --- -# 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 +57,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 +75,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 +133,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 +149,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 +169,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 +193,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..95781656a3f 100644 --- a/docs/extend/develop/using-host-dialog.md +++ b/docs/extend/develop/using-host-dialog.md @@ -1,29 +1,50 @@ --- ms.subservice: azure-devops-ecosystem -title: Modal Dialog | Extensions for Azure DevOps -description: Use the modal dialog provided by the host for Azure DevOps. +title: Create modal dialogs in Azure DevOps extensions +description: Learn how to implement modal dialogs using HostDialogService in Azure DevOps extensions with the azure-devops-extension-sdk package. Build interactive dialogs with custom content, validation, and user interactions. ms.assetid: 59748E0E-2D5E-FF79-ED0E-4B76037A8010 -ms.topic: conceptual +ms.topic: how-to +ai-usage: ai-assisted monikerRange: '<= azure-devops' ms.author: chcomley author: chcomley -ms.date: 09/19/2019 +ms.date: 07/02/2025 +# customer-intent: As an Azure DevOps extension developer, I want to create modal dialogs that block user interaction with the entire page so I can collect user input, display forms, and provide focused user experiences in my extensions. --- -# Modal dialog +# Create modal dialogs in extensions [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -The HostDialogService enables you to present a modal dialog to the user and prevent interaction with all parts of web access until the dialog is dismissed. +Modal dialogs provide a powerful way to create focused user experiences in Azure DevOps extensions. The HostDialogService lets you present a modal dialog that blocks user interaction with the entire Azure DevOps interface until the dialog gets dismissed. This action ensures that users complete important tasks or provide required information. -[!INCLUDE [extension-docs-new-sdk](../../includes/extension-docs-new-sdk.md)] +Use modal dialogs in your extensions to: +- Collect user input through forms +- Display confirmation messages for critical actions +- Show detailed information that requires user attention +- Guide users through multi-step processes -
          - In contrast to the standard dialog control, a modal dialog presented via the HostDialogService prevents interaction by the user on the entire page, not just within the extension. -
          +> [!IMPORTANT] +> When you create modal dialogs with `HostDialogService`, they block interaction with the entire Azure DevOps page, not just your extension. This approach provides a true modal experience but you should use it thoughtfully to avoid disrupting the user workflow. +## Prerequisites -### Dialog contents +Before you can create modal dialogs in your Azure DevOps extension, ensure you have the following: + +| Category | Requirement | Details | +|----------|-------------|---------| +| **Extension setup** | Working extension project | A valid `vss-extension.json` manifest file | +| | Marketplace registration | Extension registered with Visual Studio Marketplace for testing and deployment | +| | Development knowledge | Understanding of [Azure DevOps extension development basics](../get-started/node.md) | +| **Development environment** | Node.js and npm | Node.js version 14 or later with npm installed | +| | Code editor | Visual Studio Code or other IDE recommended | +| | Azure DevOps access | Access to an Azure DevOps organization for testing | +| **Required packages** | Extension SDK | Install: `npm install azure-devops-extension-sdk` | +| | Extension API | Install: `npm install azure-devops-extension-api` | +| **Extension permissions** | Manifest scopes | Include appropriate scopes in `vss-extension.json`, for example: `"vso.work"`, `"vso.project"` | +| **SDK imports** | Required modules | Import SDK and services: `import * as SDK from "azure-devops-extension-sdk"` and `import { CommonServiceIds, IHostDialogService } from "azure-devops-extension-api"` | + +## Dialog contents To start, declare a contribution of type `ms.vss-web.control` in your extension manifest. This contribution represents the content displayed within the dialog. @@ -45,7 +66,7 @@ The `uri` property references a page that is rendered within the content area of - + @@ -61,14 +82,16 @@ The `uri` property references a page that is rendered within the content area of

          - ``` -### Showing the dialog +## Show 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) { - var extensionCtx = VSS.getExtensionContext(); + import * as SDK from "azure-devops-extension-sdk"; + + SDK.getService(CommonServiceIds.HostDialogService).then((dialogService) => { + const extensionCtx = SDK.getExtensionContext(); // Build absolute contribution ID for dialogContent - var contributionId = extensionCtx.publisherId + "." + extensionCtx.extensionId + ".registration-form"; + const contributionId = `${extensionCtx.publisherId}.${extensionCtx.extensionId}.registration-form`; // Show dialog - var dialogOptions = { + const dialogOptions = { title: "My Dialog", width: 800, height: 600 @@ -136,48 +161,51 @@ To show the dialog (for example, when a user selects an action on a toolbar or m }); ``` -### Showing the dialog (advanced) +## Advanced dialog features A function can be called when the OK button is selected. This function is specified by `getDialogResult` in the options you provide when showing the dialog. If a call to `getDialogResult` returns a non-null value, this value is then passed to the function specified by `okCallback` (also in the options) and the dialog is closed. -In this example, the `attachFormChanged` callback gets called when inputs on the form change. Based on the whether the form is valid or not, the OK button is enabled or disabled. +In this example, the `attachFormChanged` callback gets called when inputs on the form change. Based on whether the form is valid or not, the OK button is enabled or disabled. ```javascript - VSS.getService(VSS.ServiceIds.Dialog).then(function(dialogService) { - var registrationForm; - var extensionCtx = VSS.getExtensionContext(); - var contributionId = extensionCtx.publisherId + "." + extensionCtx.extensionId + ".registration-form"; - - var dialogOptions = { + import * as SDK from "azure-devops-extension-sdk"; + import { CommonServiceIds, IHostDialogService } from "azure-devops-extension-api"; + + SDK.getService(CommonServiceIds.HostDialogService).then((dialogService) => { + let registrationForm: any; + const extensionCtx = SDK.getExtensionContext(); + const contributionId = `${extensionCtx.publisherId}.${extensionCtx.extensionId}.registration-form`; + + const dialogOptions = { title: "Registration Form", width: 800, height: 600, - getDialogResult: function() { + getDialogResult: () => { // Get the result from registrationForm object return registrationForm ? registrationForm.getFormData() : null; }, - okCallback: function (result) { + okCallback: (result: any) => { // Log the result to the console console.log(JSON.stringify(result)); } }; - dialogService.openDialog(contributionId, dialogOptions).then(function(dialog) { + dialogService.openDialog(contributionId, dialogOptions).then((dialog) => { // Get registrationForm instance which is registered in registrationFormContent.html - dialog.getContributionInstance("registration-form").then(function (registrationFormInstance) { + dialog.getContributionInstance("registration-form").then((registrationFormInstance) => { // Keep a reference of registration form instance (to be used previously in dialog options) registrationForm = registrationFormInstance; // Subscribe to form input changes and update the Ok enabled state - registrationForm.attachFormChanged(function(isValid) { + registrationForm.attachFormChanged((isValid: boolean) => { dialog.updateOkButton(isValid); }); // Set the initial ok enabled state - registrationForm.isFormValid().then(function (isValid) { + registrationForm.isFormValid().then((isValid: boolean) => { dialog.updateOkButton(isValid); }); }); @@ -186,20 +214,20 @@ In this example, the `attachFormChanged` callback gets called when inputs on the ``` -### Enabling or disabling the OK button +## Control the OK button Initially, the OK button is disabled. However, you can enable/disable this button by calling the `updateOkButton` method on the dialog: ```javascript - dialogService.openDialog(contributionId, dialogOptions).then(function(dialog) { + dialogService.openDialog(contributionId, dialogOptions).then((dialog) => { // Set true/false to enable/disable ok button dialog.updateOkButton(true); }); ``` -### Passing values to the dialog control +## Pass values to the dialog -It is possible pass initial values to dialog content when it is opened in the host dialog. +It's possible to pass initial values to dialog content when it is opened in the host dialog. ```json { @@ -216,7 +244,7 @@ It is possible pass initial values to dialog content when it is opened in the ho When the dialog is opened, following options need to be specified to pass `myId`: ```javascript - var dialogOptions = { + const dialogOptions = { title: "My Dialog Title", width: 800, height: 600, @@ -224,12 +252,12 @@ When the dialog is opened, following options need to be specified to pass `myId` }; ``` -### Customizing the dialog buttons +## Customize dialog buttons The `okText` and `cancelText` attributes can be used to specify alternate titles for the OK and Cancel buttons: ```javascript - var dialogOptions = { + const dialogOptions = { title: "My Dialog Title", width: 800, height: 600, @@ -241,7 +269,7 @@ The `okText` and `cancelText` attributes can be used to specify alternate titles To not show any buttons on the dialog, you can set the `buttons` attribute to `[]`: ```javascript - var dialogOptions = { + const dialogOptions = { title: "My Dialog Title", width: 800, height: 600, @@ -249,7 +277,7 @@ To not show any buttons on the dialog, you can set the `buttons` attribute to `[ }; ``` -### More information +## Related resources If you have a question or are looking for more information, consider going to one of the following areas: 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..a7a4a2e40b1 100644 --- a/docs/extend/includes/manifest-core.md +++ b/docs/extend/includes/manifest-core.md @@ -1,5 +1,5 @@ - -These properties are required: + +The following 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-discovery.md b/docs/extend/includes/manifest-discovery.md index 5994d2d6b48..4635196c9b8 100644 --- a/docs/extend/includes/manifest-discovery.md +++ b/docs/extend/includes/manifest-discovery.md @@ -1,4 +1,4 @@ -These optional properties help users discover and learn about your extension: +The following optional properties help users discover and learn about your extension: | Property | Description | Notes | 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..6f34cb84a50 100644 --- a/docs/extend/includes/procedures/update.md +++ b/docs/extend/includes/procedures/update.md @@ -1,16 +1,13 @@ -To change an extension that's already published, update it. +To update an extension you already published, do the following steps: > [!TIP] -> We recommend updating the extension over removing and re-uploading. We also recommend having two extensions, for example, `publisher.extension` and `publisher.extension-dev`. -`Publisher.extension` is public in the Marketplace, where customers can install it in their Azure DevOps organizations. `Publisher.extension-dev` is kept private in the Marketplace and can be shared with an organization that you own and control. -> You don't need to maintain two copies of source code of the extension. You can maintain two manifest files - one for each extension and during packaging of the extension you can provide the respective manifest file to the tfx-cli tool. For more information on arguments required for the tool, see [TFX extension commands](https://github.com/microsoft/tfs-cli/blob/master/docs/extensions.md#arguments). +> Update your extension instead of removing and re-uploading it. We recommend maintaining two extensions: `publisher.extension`, public in the Marketplace for customers, and `publisher.extension-dev`, private, shared only with your organization for development and testing. +> You don't need two copies of your source code—just maintain separate manifest files for each extension. When packaging, provide the appropriate manifest file to the tfx-cli tool. For more information, see [TFX extension commands](https://github.com/microsoft/tfs-cli/blob/master/docs/extensions.md#arguments). -1. Select an extension from the list of displayed items. -2. Right-click and select **Update** for the `publisher.extension-dev`, for example. +1. Select your extension from the list of displayed items. +2. Right-click and select **Update** for the development version, such as `publisher.extension-dev`. 3. Validate your extension. -4. Make the same updates to the production version, `publisher.extension`, for example. -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. - +4. Apply the same updates to the production version, such as `publisher.extension`. +5. Browse to the .vsix file for your extension and upload it. +Azure DevOps automatically installs the updated version for all accounts that already have the extension. New installations 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..ed60aa7a9e9 100644 --- a/docs/extend/publish/includes/before-publishing.md +++ b/docs/extend/publish/includes/before-publishing.md @@ -1,10 +1,10 @@ -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. -- Refrain from using brand names in the name of your extension. - +The following list of requirements must be met before you publish to the Marketplace. +| Category | Requirements | +|-------------------------|------------------| +| Packaging tool | Install the extension packaging tool (TFX). Run `npm install -g tfx-cli` from a command prompt. | +| Image permissions | Ensure you have proper permissions to use any images, like icons, logos, screenshots, and so on. | +| Marketplace overview | Include a thorough `overview.md` file to describe your listing in the Marketplace. | +| Extension icon | Include an icon for your extension that represents your integration, company, or organization, at least 128x128 pixels in size (PNG or JPEG). | +| Microsoft product names | Use full names for Microsoft products (for example, Azure DevOps instead of AzDO or other abbreviations). | +| Brand names | Don't use 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..bd19c07eb8e 100644 --- a/docs/extend/publish/includes/create-publisher.md +++ b/docs/extend/publish/includes/create-publisher.md @@ -1,24 +1,21 @@ -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. +Every extension or integration, including those from Microsoft, must have a publisher. Anyone can create a publisher and publish extensions under it. You can also share publisher access with other users, such as your development team. 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. +2. If you aren't part of an existing publisher, select **+ Create a publisher**. + Enter a publisher name; the ID field autofills based on your entry. :::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. + > - Ensure your publisher name is within 16 characters for multibyte characters. + > - Save the publisher ID—you need it in your extension's manifest file. - 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 a display name for your publisher, for example: `My Team` + If you aren't prompted to create a publisher, scroll to **Publish extensions** under *Related sites*. + * Set a unique publisher identifier, such as `mycompany-myteam`. Use this value for the `publisher` attribute in your manifest. + * Set a display name, such as `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), 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. - +After you create the publisher, you can manage items, although no items appear until you publish. diff --git a/docs/extend/publish/integration.md b/docs/extend/publish/integration.md index 879e0a7b064..071005ec591 100644 --- a/docs/extend/publish/integration.md +++ b/docs/extend/publish/integration.md @@ -7,75 +7,62 @@ ms.topic: conceptual monikerRange: '<= azure-devops' ms.author: chcomley author: chcomley -ms.date: 08/29/2016 +ms.date: 06/06/2025 --- # Package and publish an integration to the Marketplace [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -Do you have a tool, service, or product that integrates with Azure DevOps or Team Foundation Server (TFS)? -If so, help users find it by publishing it on the Visual Studio Marketplace. -The Marketplace is a one-stop-shop for individuals and teams to find tools that extend and enhance the experience. +This article explains how to publish your tool, service, or product that integrates with Azure DevOps on the Visual Studio Marketplace. Publishing on the Marketplace helps users discover solutions that extend and enhance their Azure DevOps experience. The Marketplace serves as the central hub for individuals and teams to find integrations and extensions. [Browse the Marketplace](https://marketplace.visualstudio.com) to see examples of other integrations and extensions. > [!NOTE] -> If you're looking for packaging and publishing information for extensions, check out [Package & Publish Extensions](overview.md). +> For packaging and publishing information for extensions, see [Package & Publish Extensions](overview.md). -## Publishing requirements +## Prerequisites [!INCLUDE [](includes/before-publishing.md)] -## What you need +### Gather required assets -1. 128x128 pixel logo (PNG or JPEG format) representing your integration, yourself, or your company/organization -2. Minimum of one screenshot showing your integration -3. Call to action / get started URL (where users should go to get started with your integration) +- At least one screenshot of your integration. +- Call-to-action or get started URL for users. -## Steps - -Publishing to the Marketplace is an iterative process that starts with creating a manifest file that defines your integration and key discovery characteristics (like screenshots, logos, and overview content). This information is used to present your integration to users on the Marketplace, for example: - -![example](./media/integration-example.png) - -[Jenkins for Azure DevOps](https://marketplace.visualstudio.com/items?itemName=ms-vsts.services-jenkins) - -Note: The term, `extension`, is used in documentations referenced below. Extensions are another type of Marketplace item and share many similarities from a discovery standpoint as integrations. - -
        - Need help with getting your integration on the Marketplace? Contact us. And, yes, this e-mail address is monitored by real people. -
        +> [!NOTE] +> - The term `extension` is used in referenced documentation. Extensions are another type of Marketplace item and share many similarities with integrations. +> - Need help getting your integration on the Marketplace? [Contact us](https://go.microsoft.com/fwlink/?LinkId=615292). -### Create a publisher +### Create a publisher account [!INCLUDE [](./includes/create-publisher.md)] -### Create a folder to contain your item manifest and other assets +### Organize your manifest and assets -Before you package your integration as an extension, you'll need to create a `home` folder to contain some required assets, within this folder: +To organize your manifest and assets, do the following steps: -1. Create a folder called `images` to contain: - * Logo for your integration (128x128 pixels) +1. Create a `home` folder to store required assets. +2. Create an `images` folder for: + * Your integration logo (128x128 pixels) * Screenshots (1366x768 pixels) -2. Create a file called `overview.md` - * Describe your integration here - * To learn more about Markdown, see [GitHub Flavored Markdown](https://help.github.com/articles/github-flavored-markdown/) -3. Create a file called `vss-integration.json` - * This file is your Marketplace listing's manifest file, it contains many properties to describe your extension in your Marketplace listing. You can browse the [extension manifest reference here](../develop/manifest.md) +3. Create an `overview.md` file to describe your integration. For more information, see [GitHub Flavored Markdown](https://help.github.com/articles/github-flavored-markdown/). +4. Create a `vss-integration.json` file, which is your Marketplace listing's manifest file. For more information, see the [extension manifest reference](../develop/manifest.md). -#### Extension Manifest +#### Complete the extension manifest + +Publishing to the Marketplace starts with creating a manifest file that defines your integration and its key discovery details (screenshots, logos, overview content). This information is used to present your integration to users on the Marketplace. 1. Fill your `vss-integration.json` file with the following JSON: [!code-javascript[JSON](../_data/integration.json)] -2. Update the JSON using the following reference: +2. Update the JSON using the following references: [!INCLUDE [](../includes/manifest-core.md)] [!INCLUDE [](../includes/manifest-discovery.md)] -#### Details page +#### Understand the details page * 1 - description * 2 - icon @@ -85,20 +72,20 @@ Before you package your integration as an extension, you'll need to create a `ho * 6 - links * 7 - branding -![card](../develop/media/extension-details-page.png) +![Screenshot shows details card for extension in the Visual Studio Marketplace.](../develop/media/extension-details-page.png) -
        - Make sure the "public" attribute gets set to "false" (or not set at all) to avoid your extension or integration from becoming prematurely visible to all users on the Marketplace. -
        +> [!WARNING] +> Set the `public` attribute to `false` or omit it to prevent your integration from becoming visible to all Marketplace users before you're ready. ### Package your manifest and assets -#### Get the package tool (tfx-cli) -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. +#### Install the package tool (tfx-cli) -```no-highlight +Install or update the cross-platform CLI for Azure DevOps (tfx-cli) using `npm`: + +```bash npm i -g tfx-cli ``` @@ -109,29 +96,27 @@ tfx extension create --manifest-globs vss-extension.json ``` > [!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 with every update. +> If you haven't updated the version in your manifest, use the `--rev-version` command line switch. This switch automatically increments the *patch* version number and saves the new version to your manifest. ### Publish your integration to the Marketplace [!INCLUDE [Publish_extension](../includes/procedures/publish.md)] ### Share your integration -Before you can install an integration into an organization in Azure DevOps or TFS, you must share it with that organization. Sharing is a requirement during development and testing of an integration, as it's the only way to run an integration. -To share an integration do the following tasks: +Before installing an integration in an Azure DevOps organization, share it with that organization. Sharing is required for development and testing, as it's the only way to run an integration during these stages. + +To share an integration do the following steps: 1. Select an integration from the list of displayed items 2. Select the **Share** button -3. Specify the name of the organization to make this integration visible to. - - For example, to make an integration visible to the **dev.azure.com/fabrikam-fiber-inc** organization, specify `fabrikam-fiber-inc`. +3. Specify the name of the organization to make this integration visible to. For example, to make an integration visible to the **dev.azure.com/fabrikam-fiber-inc** organization, specify `fabrikam-fiber-inc`. #### Update an item [!INCLUDE [Update_extension](../includes/procedures/update.md)] -## Make your integration public (visible to everyone) - -For information on making your integration public, visit [Make your listing public](./publicize.md). - +## Make your integration public +For information on making your integration visible to everyone, see [Make your listing public](./publicize.md). 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..10f915dce0a 100644 --- a/docs/extend/publish/overview.md +++ b/docs/extend/publish/overview.md @@ -1,21 +1,24 @@ --- 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 +ms.custom: + - engagement-fy23 + - sfi-image-nochange --- # 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 +31,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 +55,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 +66,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 +94,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 +149,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..b62e112d30c 100644 --- a/docs/extend/reference/targets/overview.md +++ b/docs/extend/reference/targets/overview.md @@ -1,63 +1,51 @@ --- -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 ms.author: chcomley author: chcomley monikerRange: '<= azure-devops' ms.topic: overview -ms.date: 10/12/2022 +ms.date: 04/11/2025 +ms.custom: + - engagement-fy23 + - sfi-image-nochange --- # 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 +71,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 +103,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 +215,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..bf8c90ef35e 100644 --- a/docs/get-started/index.yml +++ b/docs/get-started/index.yml @@ -7,11 +7,13 @@ 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 + ms.update-cycle: 1095-days manager: jillfra # linkListType: architecture | concept | deploy | download | get-started | how-to-guide | learn | overview | quickstart | reference | tutorial | video | whats-new @@ -32,8 +34,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 +50,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 +68,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 +92,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 +108,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 +144,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-project-administrators.md b/docs/includes/get-started/add-project-administrators.md index 670189f02cc..327a08873c5 100644 --- a/docs/includes/get-started/add-project-administrators.md +++ b/docs/includes/get-started/add-project-administrators.md @@ -3,13 +3,9 @@ ms.subservice: azure-devops-new-user ms.author: chcomley author: chcomley ms.topic: include -ms.date: 02/25/2022 +ms.date: 05/05/2025 --- - - -The person who creates a project is automatically added as a member to the **Project Administrators** group. Members of this group have permissions to manage project configuration, repositories, pipeline resources, teams, and all project-level permissions. - -It's always a good idea to have more than one person who has administrative privileges. To add a user to this group, see [Change permissions at the project level, Add members to the Project Administrators group](../../organizations/security/change-project-level-permissions.md#add-members-to-the-project-administrators-group). - +The person who creates a project is automatically added as a member to the **Project Administrators** group. Members of this group have permissions to manage project configuration, repositories, pipeline resources, teams, and all project-level permissions. +It's a good practice to assign administrative privileges to more than one team member. You can add a user to this group by following the instructions in [Change permissions at the project level, Add members to the Project Administrators group](../../organizations/security/change-project-level-permissions.md#add-members-to-the-project-administrators-group). \ No newline at end of file diff --git a/docs/includes/get-started/add-teams-to-scale.md b/docs/includes/get-started/add-teams-to-scale.md index d208c373fce..adb878fa785 100644 --- a/docs/includes/get-started/add-teams-to-scale.md +++ b/docs/includes/get-started/add-teams-to-scale.md @@ -3,19 +3,17 @@ ms.subservice: azure-devops-new-user ms.author: chcomley author: chcomley ms.topic: include -ms.date: 02/25/2022 +ms.date: 05/05/2025 --- +## Add teams and scale your project -## Add teams to scale your project +As your organization grows, it's a good practice to add teams to scale your project. Each team gets [access to their own set of customizable Agile tools](../../organizations/settings/about-teams-and-settings.md). -As your organization grows, we recommend that you add teams to scale your project. Each team gets [access to their own set of customizable Agile tools](../../organizations/settings/about-teams-and-settings.md). +:::image type="content" source="../../organizations/settings/media/agile-tools/agile-tools-team-assets-post-2018.png" border="false" alt-text="Diagram of Agile tools and team assets organized to support planning - tracking, monitoring - learning, and collaboration." lightbox="../../organizations/settings/media/agile-tools/agile-tools-team-assets-post-2018.png"::: -![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) -- [Add a team administrator](../../organizations/settings/add-team-administrator.md) - +- [Add a team, move from one default team to several teams](../../organizations/settings/add-teams.md) +- [Add a team administrator](../../organizations/settings/add-team-administrator.md) \ No newline at end of file diff --git a/docs/includes/get-started/add-users-project.md b/docs/includes/get-started/add-users-project.md index bcad9b716bc..6fbbd2c638d 100644 --- a/docs/includes/get-started/add-users-project.md +++ b/docs/includes/get-started/add-users-project.md @@ -3,25 +3,23 @@ ms.subservice: azure-devops-new-user ms.author: chcomley author: chcomley ms.topic: include -ms.date: 02/25/2022 +ms.date: 05/05/2025 --- - +## Add users to your project -## Add users to your project +You add users to a team or project so they can contribute to the team and project. Users can be added to multiple teams and projects. -You add users to a team or project so they can contribute to the team and project. Users can be added to multiple teams and projects. +Users who are added to an organization, can easily be added to a project by adding them to a team or inviting them to contribute to a project. -Users that have been added to an organization, can easily be added to a project by adding them to a team or inviting them to contribute to a project. +Team administrators can add users to their team, which automatically adds them to the project. By adding users to a team, the users become visible to team-specific tools like the team security group, Team Members widget, and sprint capacity planning tools. To learn more about teams, see [About teams and Agile tools](../../organizations/settings/about-teams-and-settings.md). -Team administrators can add users to their team which automatically adds them to the project. 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. To learn more about teams, see [About teams and Agile tools](../../organizations/settings/about-teams-and-settings.md). +Members of the **Project Administrators** group can add users to a project. Adding users to a team or project automatically adds them to the project's **Contributors** group. Members of this group have permissions to most features needed to contribute to work items, code, builds, and releases. For an overview of default permissions, see [Default permissions quick reference](../../organizations/security/permissions-access.md). -Members of the **Project Administrators** group can add users to a project. Adding users to a team or project automatically adds them to the project's **Contributors** group. Members of this group have permissions to most features needed to contribute to work items, code, builds, and releases. For an overview of default permissions, see [Default permissions quick reference](../../organizations/security/permissions-access.md). +After users are 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. - 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: -- [Add users or groups to a team or project](../../organizations/security/add-users-team-project.md) +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) - +- [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..a8a6d0259f4 100644 --- a/docs/includes/get-started/customize-work-tracking.md +++ b/docs/includes/get-started/customize-work-tracking.md @@ -3,34 +3,18 @@ ms.subservice: azure-devops-security ms.author: chcomley author: chcomley ms.topic: include -ms.date: 04/04/2022 +ms.date: 05/05/2025 --- - - - ### Customize work-tracking processes -You and your team can start using all work-tracking tools immediately after you create a project. But often, one or more users want to customize the experience to meet one or more business needs. You can customize the process easily through the user interface. As such, you'll want to establish a methodology for who will manage the updates and evaluate requests. +You and your team can start using all work-tracking tools immediately after you create a project. But often, some users want to customize the experience to meet various business needs. You can customize the process easily through the user interface. It's a good practice to establish a methodology for which users can manage the updates and evaluate requests. > [!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: - -::: moniker range=">= azure-devops-2019" - -- [About process customization and inherited processes](../../organizations/settings/work/inheritance-process-model.md) -- [Customize a project](../../organizations/settings/work/customize-process.md) -- [Add and manage processes](../../organizations/settings/work/manage-process.md) - -::: 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) +For more information, see the following articles: -::: moniker-end - \ No newline at end of file +- [About process customization and inherited processes](../../organizations/settings/work/inheritance-process-model.md) +- [Customize a project](../../organizations/settings/work/customize-process.md) +- [Add and manage processes](../../organizations/settings/work/manage-process.md) \ 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..68429626fdb 100644 --- a/docs/includes/get-started/define-area-iteration-paths.md +++ b/docs/includes/get-started/define-area-iteration-paths.md @@ -3,18 +3,17 @@ ms.subservice: azure-devops-new-user ms.author: chcomley author: chcomley ms.topic: include -ms.date: 02/28/2022 +ms.date: 05/05/2025 --- - +### Define area and iteration paths for tracking work -### Define area and iteration paths to track work +If you support several products, you can assign work items according to feature area by defining [area paths](../../organizations/settings/set-area-paths.md). To assign work items to specific time intervals, also known as _sprints_, you configure [iteration paths](../../organizations/settings/set-iteration-paths-sprints.md). To use the Scrum tools like sprint backlogs, taskboards, and team capacity, you need to configure several sprints. For an overview, see [About areas and iteration paths](../../organizations/settings/about-areas-iterations.md). -If you support several products, you can assign work items by feature area by defining [area paths](../../organizations/settings/set-area-paths.md). To assign work items to specific time intervals, also known as sprints, you configure [iteration paths](../../organizations/settings/set-iteration-paths-sprints.md). To use the Scrum tools—sprint backlogs, taskboards, and team capacity—you need to configure several sprints. For an overview, see [About areas and iteration paths](../../organizations/settings/about-areas-iterations.md). +The following image shows default iteration paths for Scrum processes: +:::image type="content" source="../../organizations/settings/media/areas/areas-iterations-iterations-intro-ts-2016.png" border="false" alt-text="Screenshot showing default iterations for Scrum processes."::: -> [!div class="mx-tdBreakAll"] -> |Iterations| Areas | -> |-------------|----------| -> |![Default iterations, Scrum process](../../organizations/settings/media/areas/areas-iterations-iterations-intro-ts-2016.png) | ![A set of sample area paths](../../organizations/settings/media/areas/areas-iterations-areas-intro-ts-2016.png) | - \ No newline at end of file +The following image shows a set of sample area paths: + +:::image type="content" source="../../organizations/settings/media/areas/areas-iterations-areas-intro-ts-2016.png" border="false" alt-text="Screenshot showing a set of sample area paths."::: \ No newline at end of file diff --git a/docs/includes/get-started/determine-traceability-requirements.md b/docs/includes/get-started/determine-traceability-requirements.md index f728b6be0b8..eb4d0dd751e 100644 --- a/docs/includes/get-started/determine-traceability-requirements.md +++ b/docs/includes/get-started/determine-traceability-requirements.md @@ -3,12 +3,12 @@ ms.subservice: azure-devops-new-user ms.author: chcomley author: chcomley ms.topic: include -ms.date: 02/28/2022 +ms.date: 05/05/2025 --- ## Determine traceability requirements -If you're using most of Azure DevOps Services—Boards, Repos, Pipelines, and Test Plans— you'll want to alert your teams to those features that support end-to-end traceability. To get started, we recommend that you review the following articles: +If you use most Azure DevOps Services, such as Azure Boards, Azure Repos, Azure Pipelines, and Azure Test Plans, you probably want to alert your teams to the features that support end-to-end traceability. You can get started by reviewing the following articles: - [Cross-service integration and collaboration overview](../../cross-service/cross-service-overview.md) - [End-to-end traceability](../..//cross-service/end-to-end-traceability.md) \ No newline at end of file diff --git a/docs/includes/get-started/enable-remove-services.md b/docs/includes/get-started/enable-remove-services.md index 1c56c5c458a..384a7985810 100644 --- a/docs/includes/get-started/enable-remove-services.md +++ b/docs/includes/get-started/enable-remove-services.md @@ -3,19 +3,13 @@ ms.subservice: azure-devops-new-user ms.author: chcomley author: chcomley ms.topic: include -ms.date: 02/25/2022 +ms.date: 05/05/2025 --- +## Remove unused services -::: moniker range=">= azure-devops-2019" +To simplify the web portal user interface, you can disable specific services. Suppose you use a project only to log bugs. In this scenario, you might disable all services except for **Boards**. For more information, see [Turn a service on or off](../../organizations/settings/set-services.md). -## Remove unused services +The following example shows the **Test Plans** service disabled: -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). - -This example shows that **Test Plans** is disabled: - -> [!div class="mx-imgBorder"] -> ![Disable a service](../../user-guide/media/services/set-service-visibility.png) - -::: moniker-end \ No newline at end of file +:::image type="content" source="../../user-guide/media/services/set-service-visibility.png" border="false" alt-text="Screenshot that shows the Test Plans service disabled in the Project Settings page for Azure DevOps Services."::: \ No newline at end of file diff --git a/docs/includes/get-started/review-notifications.md b/docs/includes/get-started/review-notifications.md index db4cf06a84d..012cd5205c0 100644 --- a/docs/includes/get-started/review-notifications.md +++ b/docs/includes/get-started/review-notifications.md @@ -3,20 +3,16 @@ ms.subservice: azure-devops-new-user ms.author: chcomley author: chcomley ms.topic: include -ms.date: 02/28/2022 +ms.date: 05/05/2025 --- - ## Review and update notifications -A number of notifications are predefined for each project you add. Notifications are based on subscription rules. Subscriptions arise from the following areas: +Several notifications are predefined for each project you add. Notifications are based on subscription rules. Subscriptions arise from the following areas: - [Out-of-the-box or default subscriptions](../../organizations/notifications/oob-built-in-notifications.md). - [Team, project, and organization or collection subscriptions](../../organizations/notifications/manage-team-group-global-organization-notifications.md) defined by a team administrator or member of the **Project Administrators** or **Project Collection Administrators** groups. -If users believe they're getting too many notifications, you can direct them to [opt out of a subscription](../../organizations/notifications/manage-your-personal-notifications.md). +If users report receiving too many notifications, you can direct them to [opt out of a subscription](../../organizations/notifications/manage-your-personal-notifications.md). -> [!div class="mx-imgBorder"] -> ![Personal notifications](../../user-guide/media/services/personal-notifications.png) - - \ No newline at end of file +:::image type="content" source="../../user-guide/media/services/personal-notifications.png" alt-text="Screenshot that shows how users can opt out of various types of notifications."::: \ No newline at end of file diff --git a/docs/includes/get-started/share-project-vision.md b/docs/includes/get-started/share-project-vision.md index 500f93d2c4b..dceb7900647 100644 --- a/docs/includes/get-started/share-project-vision.md +++ b/docs/includes/get-started/share-project-vision.md @@ -3,23 +3,9 @@ ms.subservice: azure-devops-new-user ms.author: chcomley author: chcomley ms.topic: include -ms.date: 04/04/2022 +ms.date: 05/05/2025 --- - - - -## Share your project vision, set up a project wiki - - -::: moniker range="azure-devops" - -Each project has a summary page that's useful for sharing information through **README** files. Or, redirect users to a project Wiki. For users who are new to your project, we recommend that you [set up your project summary page](../../organizations/projects/project-vision-status.md). Or, you can [provision a Wiki](../../project/wiki/wiki-create-repo.md). Use these features to share established processes and procedures for your project. - -::: moniker-end - -::: moniker range="< azure-devops" -Each project has a summary page that's useful for sharing information through **README files**. For users who are new to your project, we recommend that you [set up your project summary page](../../organizations/projects/project-vision-status.md). Or, you can [provision a Wiki](../../project/wiki/wiki-create-repo.md). Use these features to share established processes and procedures for your project. - -::: moniker-end +## Share your project vision, set up a project wiki +Each project has a summary page that's useful for sharing information through **README** files. You can also redirect users to a project Wiki. For users who are new to your project, a good approach is to [set up your project summary page](../../organizations/projects/project-vision-status.md) or [prepare a Wiki](../../project/wiki/wiki-create-repo.md). Use these features to share established processes and procedures for your project. 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/images-not-appearing-vs.md b/docs/includes/images-not-appearing-vs.md index 8559ee01c39..54d5a1da53b 100644 --- a/docs/includes/images-not-appearing-vs.md +++ b/docs/includes/images-not-appearing-vs.md @@ -1,14 +1,18 @@ --- ms.topic: include +ms.date: 04/24/2025 --- - - ### Resolve images that don't display in Team Explorer -If an inline image isn't displayed in a work item form that you view in Visual Studio Team Explorer, but the image is displayed in the web portal, your credentials might have expired. You can resolve this by completing the following steps: +You might see an image in the web portal that doesn't display as expected within a work item form in Visual Studio Team Explorer. Expired credentials are a common cause of this issue. + +You can try resolving the issue with the following steps: + +1. In Visual Studio, select **View** > **Other Windows** > **Web Browser** (or use the keyboard shortcut **Ctrl+Alt+R**). + +1. In the web browser, locate your organization. + +1. Sign in with your credentials. -1. In Visual Studio, select **View** > **Other Windows** > **Web Browser** (or use the shortcut **Ctrl+Alt+R**). -2. In the web browser, locate your organization. -3. Sign in with your credentials. -4. Refresh your work item in Team Explorer. +1. Refresh your work item in Team Explorer. 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..b7741998e4b 100644 --- a/docs/includes/manage-policies.md +++ b/docs/includes/manage-policies.md @@ -4,14 +4,14 @@ 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 update application connection, security, or user policies for your organization, follow these steps: -1. Sign in to your organization (```https://dev.azure.com/{yourorganization}```). +1. Sign in to your organization at `https://dev.azure.com/{Your_Organization}`. 2. Select ![gear icon](../media/icons/gear-icon.png) **Organization settings**. ![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**, then toggle the desired policy **on** or **off**. - ![Screenshot of select policy, and then turn On or Off.](../media/change-policies-preview.png) + ![Screenshot of policies list and their on and off toggles.](../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..0f33814f531 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"? -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. +A: 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..00b88adbbc3 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. - +A: 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..f2c9e2763e5 100644 --- a/docs/includes/sign-up-msft-account.md +++ b/docs/includes/sign-up-msft-account.md @@ -1,30 +1,17 @@ --- ms.topic: include +ms.custom: sfi-image-nochange --- ## 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..14c1ac55c00 --- /dev/null +++ b/docs/includes/use-microsoft-entra-reduce-pats.md @@ -0,0 +1,7 @@ +--- +ms.topic: include +--- + +> [!IMPORTANT] +> We recommend the more secure [Microsoft Entra tokens](../integrate/get-started/authentication/entra.md) over higher-risk [personal access tokens](../organizations/accounts/use-personal-access-tokens-to-authenticate.md). Learn more about our efforts to [reduce PAT usage](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 right 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/when-to-refresh-client.md b/docs/includes/when-to-refresh-client.md index 1383dce4278..e261f3626e6 100644 --- a/docs/includes/when-to-refresh-client.md +++ b/docs/includes/when-to-refresh-client.md @@ -1,9 +1,17 @@ -To avoid potential errors, you should refresh your client application under the following circumstances: +--- +ms.author: chcomley +author: chcomley +ms.service: azure-devops +ms.topic: include +ms.date: 04/24/2025 +--- -- Process changes are made -- Work item type definitions are added, removed, renamed, or updated -- Area or iteration paths are added, removed, renamed, or updated -- Users are added to or removed from security groups or permissions are updated -- A team member adds a new shared query or changes the name of a shared query -- A build definition is added or deleted -- A team or project is added or deleted +To avoid potential errors, you should refresh your client application in the following scenarios: + +- Process change applied +- Work item type definition added, removed, renamed, or updated +- Area or iteration path added, removed, renamed, or updated +- User added or removed in security groups, or user permissions updated +- New shared query added or existing shared query updated +- Build definition added or deleted +- Team or project added or deleted 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..aaba83624d5 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,30 +214,28 @@ 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: About authentication, authorization, and security policies + url: ./organizations/security/about-security-identity.md - text: Add or remove users or groups url: ./organizations/security/add-remove-manage-user-group-security-group.md - 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 +250,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 +269,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 +287,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 @@ -306,39 +300,31 @@ additionalContent: - text: See more > url: ./project/index.yml # Card + - title: Developer resources + links: + - text: Authentication overview + url: ./integrate/get-started/authentication/authentication-guidance.md?toc=/azure/devops/dev-resources/toc.json + - text: Build with Azure DevOps + url: ./integrate/index.md?toc=/azure/devops/dev-resources/toc.json + - text: Azure DevOps CLI + url: ./cli/index.md?toc=/azure/devops/dev-resources/toc.json + - text: Get started with REST APIs + url: ./integrate/how-to/call-rest-api.md?toc=/azure/devops/dev-resources/toc.json + - text: REST API Reference + url: /rest/api/azure/devops/ + - text: See more > + url: ./dev-resources/index.yml + # Card - title: Marketplace & Extensibility links: - 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 > url: ./marketplace-extensibility/index.yml - # Card - - title: Developer resources - links: - - text: Azure DevOps CLI - url: ./cli/index.md?toc=/azure/devops/dev-resources/toc.json - - text: Azure DevOps CLI quick reference - url: ./cli/quick-reference.md?toc=/azure/devops/dev-resources/toc.json - - 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 - - text: Azure DevOps Services Demo Generator - url: ./demo-gen/index.md?toc=/azure/devops/dev-resources/toc.json - - text: REST APIs - url: /rest/api/vsts/ - - text: DevOps resource center - url: /devops - - text: See more > - 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..9cf83f745b4 100644 --- a/docs/integrate/concepts/dotnet-client-libraries.md +++ b/docs/integrate/concepts/dotnet-client-libraries.md @@ -1,97 +1,95 @@ --- -title: .NET Client Libraries -description: Easily integrate with Azure DevOps from apps and services on Windows. +title: .NET client libraries +description: Learn how to use Azure DevOps .NET client libraries to integrate work items, Git repositories, builds, and pipelines into your C# applications and Windows services. ms.assetid: 474cdb4f-9a5e-49fb-84b2-9c540ebcf98b +ai-usage: ai-assisted ms.subservice: azure-devops-ecosystem ms.custom: devx-track-dotnet ms.topic: conceptual monikerRange: '<= azure-devops' ms.author: chcomley author: chcomley -ms.date: 07/28/2022 +ms.date: 07/02/2025 +#customer intent: As a .NET developer, I want to integrate my C# applications with Azure DevOps services like work items, Git repositories, builds, and pipelines using official client libraries and REST APIs. --- # .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`| -|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`| +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`| 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`. +> **Legacy SOAP APIs**: If you have an existing Windows application that uses the TFS Client Object Model, use `Microsoft.TeamFoundationServer.ExtendedClient` for SOAP-based APIs. This package is only recommended when REST APIs don't provide the specific functionality you need (such as TFVC workspace creation). This package doesn't support .NET Standard and Microsoft is no longer investing in SOAP-based APIs. ## 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: @@ -101,18 +99,21 @@ using Microsoft.VisualStudio.Services.Client; using Microsoft.TeamFoundation.SourceControl.WebApi; using Microsoft.VisualStudio.Services.WebApi; -const String c_collectionUri = "https://dev.azure.com/fabrikam"; -const String c_projectName = "MyGreatProject"; -const String c_repoName = "MyRepo"; +const string collectionUri = "https://dev.azure.com/fabrikam"; +const string projectName = "MyGreatProject"; +const string repoName = "MyRepo"; +const string accessToken = "your-microsoft-entra-id-token"; -// Connect to Azure DevOps Services -VssConnection connection = new VssConnection(orgUrl, new VssBasicCredential(string.Empty, personalAccessToken)); +Uri orgUrl = new Uri(collectionUri); + +// Connect to Azure DevOps using Microsoft Entra ID token +VssConnection connection = new VssConnection(orgUrl, new VssBasicCredential(string.Empty, accessToken)); // Get a GitHttpClient to talk to the Git endpoints using (GitHttpClient gitClient = connection.GetClient()) { // Get data about a specific repository - var repo = gitClient.GetRepositoryAsync(c_projectName, c_repoName).Result; + var repo = gitClient.GetRepositoryAsync(projectName, repoName).Result; } ``` @@ -131,13 +132,13 @@ namespace ConsoleApp1 const string collectionUri = "https://dev.azure.com/fabrikam"; const string projectName = "MyGreatProject"; const string repoName = "MyRepo"; - const string pat = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"; + const string accessToken = "your-microsoft-entra-id-token"; static void Main(string[] args) { - var creds = new VssBasicCredential(string.Empty, pat); + var creds = new VssBasicCredential(string.Empty, accessToken); - // Connect to Azure DevOps Services + // Connect to Azure DevOps Services using Microsoft Entra ID token var connection = new VssConnection(new Uri(collectionUri), creds); // Get a GitHttpClient to talk to the Git endpoints @@ -151,7 +152,10 @@ namespace ConsoleApp1 ``` -Further authentication samples can be found on our [.NET Samples page](../get-started/client-libraries/samples.md). +> [!TIP] +> **Microsoft Entra ID authentication**: The previous examples use Microsoft Entra ID tokens for authentication. For more information, see [Authenticate to Azure DevOps using Microsoft Entra](../get-started/authentication/entra.md). + +For more authentication samples, see [.NET Samples](../get-started/client-libraries/samples.md). ## Reference @@ -159,19 +163,15 @@ For more information and for up-to-date reference documentation, see the [.NET A ## Samples -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" +Check out samples on our [.NET Samples Page](../get-started/client-libraries/samples.md). 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 +183,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); ... @@ -192,8 +194,11 @@ async void InitAzureDevOps() ### Using NetStandard 2.0 versions of the Azure DevOps OM -For version 16.143.1 of our NuGet packages, we support NetStandard 2.0. These packages correlate with Azure DevOps Server 2019 RTW and are fully compatible with Azure DevOps. +For version 16.143.1 of our NuGet packages, we support NetStandard 2.0. These packages correlate with Azure DevOps Server and are fully compatible with Azure DevOps. ### 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..5fb61ac8577 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/overview.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 deleted file mode 100644 index f4f7fb0c5da..00000000000 --- a/docs/integrate/concepts/service-hooks.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -title: Service hooks in Azure DevOps Services REST APIs -description: Learn about service hooks and how to set up actions to take when specific events occur in Azure DevOps Services. -ms.assetid: ec039cf9-2731-4451-b9b8-5711b229c0ff -ms.subservice: azure-devops-ecosystem -ms.topic: conceptual -monikerRange: 'azure-devops' -ms.author: chcomley -author: chcomley -ms.date: 03/25/2022 ---- - -# Service hooks in Azure DevOps - -[!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. - -Supported events: -- Build completed -- Code pushed (for Git projects) -- Pull request create or updated (for Git projects) -- Code checked in (TFVC projects) -- Work item created, updated, deleted, restored or commented on - -You can configure filters on your subscriptions to control which events trigger an action. For example, you can filter the build completed event based on the build status. For a complete set of supported events and filter options, see the [event reference](../../service-hooks/events.md). - -For a complete set of supported consumer services and actions, see the [consumer reference](../../service-hooks/consumers.md). diff --git a/docs/integrate/get-started/auth/tfs-basic-auth.md b/docs/integrate/get-started/auth/tfs-basic-auth.md index 4c3a6cde677..fbb6cb60bc1 100644 --- a/docs/integrate/get-started/auth/tfs-basic-auth.md +++ b/docs/integrate/get-started/auth/tfs-basic-auth.md @@ -1,92 +1,129 @@ --- ms.subservice: azure-devops-ecosystem ms.topic: conceptual -title: Use the Cross-platform CLI for Azure DevOps -description: Use the Cross-platform CLI for Azure DevOps, using personal access tokens (PATs). +title: Cross-platform CLI authentication for Azure DevOps +description: Learn authentication options for the cross-platform CLI for Azure DevOps, including Microsoft Entra ID tokens and personal access tokens. ms.assetid: 6dc7f977-4b62-4bd6-b77a-1c6cade1ffa8 monikerRange: '<= azure-devops' ms.author: chcomley author: chcomley -ms.date: 10/20/2020 +ms.date: 07/14/2025 --- -# Use the Cross-platform CLI for Azure DevOps using personal access tokens (PATs) +# Cross-platform CLI authentication for Azure DevOps [!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** - - Install **tfx-cli** using `npm`, a component of Node.js by running: +This article explains authentication approaches for the cross-platform CLI (tfx-cli) and Azure DevOps. - ```no-highlight - npm i -g tfx-cli +> [!IMPORTANT] +> We recommend using [Microsoft Entra ID authentication](../authentication/entra.md) as the primary method for authentication. Personal access tokens (PATs) should be used only when Microsoft Entra ID authentication isn't available. Basic authentication is deprecated and not recommended. + +## Prerequisites + +Before you begin, ensure you have: + +- [Node.js](https://nodejs.org/en/download/) (latest LTS version recommended) +- **tfx-cli** installed globally: + + ```bash + npm install -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 +## Authentication methods -Start by creating a personal access token and paste it into the sign in command. +Choose the appropriate authentication method based on your environment: -``` -~$ tfx login -Copyright Microsoft Corporation +| Method | Recommended for | +|--------|----------------| +| Microsoft Entra ID | Azure DevOps Services | +| PAT | Azure DevOps Server, automation scripts | +| Basic Authentication | Azure DevOps Server only | -> Service URL: {url} -> Personal access token: xxxxxxxxxxxx -Logged in successfully +## Microsoft Entra ID authentication (Recommended) + +For Azure DevOps Services, use Microsoft Entra ID authentication for the best security: + +```bash +tfx login ``` -Examples of valid URLs are: +When prompted: +1. Enter your service URL, for example, `https://dev.azure.com/Your_Organization`. +2. Follow the browser-based authentication flow. +3. Complete the sign-in process in your browser. -- `https://marketplace.visualstudio.com` -- `https://youraccount.visualstudio.com/DefaultCollection` +For detailed guidance on Microsoft Entra ID authentication, see [Microsoft Entra-based authentication](../authentication/entra.md). -## Configure for Basic authentication +## PAT 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. +Use PATs when Microsoft Entra ID authentication isn't available, such as with Azure DevOps Server. -Follow these steps to enable basic auth for your Azure DevOps instance: +### Create and use a PAT -> [!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. +1. [Create a PAT](../../../organizations/accounts/use-personal-access-tokens-to-authenticate.md) with the required scopes. +2. Sign in using the PAT: -1. Install the `Basic Authentication` feature for IIS in Server Manager + ```bash + tfx login + ``` - > [!div class="mx-imgBorder"] - > ![Screenshot of configure basic authentication feature.](./media/configureBasicAuthFeature.png) +3. When prompted, provide: + - **Service URL**: Your Azure DevOps instance URL. + - **Personal access token**: The PAT you created. -2. Open IIS Manager and expand to the `Azure DevOps Server` website, double-click the `Authentication` tile in the Features view. +**Example URLs:** +- Azure DevOps Services: `https://dev.azure.com/Your_Organization` +- Azure DevOps Server: `https://yourserver/tfs/DefaultCollection` +- Visual Studio Marketplace: `https://marketplace.visualstudio.com` -3. Choose `Basic Authentication` in the list of authentication methods. Choose `Enable` in the right hand column. You should now see `Basic Authentication` enabled. +**Example session:** +``` +~$ tfx login +Copyright Microsoft Corporation + +> Service URL: https://dev.azure.com/Your_Organization +> Personal access token: ********************** +Logged in successfully +``` -> [!NOTE] -> Leave the **domain** and **realm** settings for Basic Authentication empty. +## Basic authentication (Deprecated) -## tfx sign in with Basic authentication +> [!WARNING] +> Basic authentication is deprecated and not recommended. Use Microsoft Entra ID instead. Basic authentication: +> - Sends credentials in plaintext +> - Can cause issues with Git command line operations +> - Poses security risks -Now you can start to use `tfx` against your server. You'll want to sign in before issuing commands. +### Configure basic authentication (Azure DevOps Server only) -1. Enter the following command: +If you must use basic authentication with Azure DevOps Server installations: - ```no-highlight - tfx login --auth-type basic - ``` +1. **Enable IIS Basic Authentication:** + - Open Server Manager. + - Install the Basic Authentication feature for IIS. + - In IIS Manager, go to your Azure DevOps Server website. + - Double-select **Authentication** in the Features view. + - Enable Basic Authentication. + - Leave domain and realm settings empty. -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`. -4. Add your password. Enter the password for the username that you previously entered. +2. **Sign in with basic authentication:** -**You can now use any other tfx command.** + ```bash + tfx login --auth-type basic + ``` -```no-highlight -> tfx login --auth-type basic -Copyright Microsoft Corporation +3. When prompted, provide: + - **Service URL**: Your on-premises server URL (for example, `http://yourserver:8080/tfs/DefaultCollection`). + - **Username**: Use `domain\username` format (for example, `fabrikam\john`) + - **Password**: Your domain password. -Enter service url > http://localhost:8080/tfs/defaultcollection -Enter username > fabfiber\peter -Enter password > ******* -logged in successfully -``` +> [!TIP] +> Consider [configuring SSL](/azure/devops/server/admin/setup-secure-sockets-layer) for secure communication when using basic authentication. + +## Next step + +> [!div class="nextstepaction"] +> [View the complete tfx-cli command reference](https://github.com/Microsoft/tfs-cli) diff --git a/docs/integrate/get-started/authentication/authentication-guidance.md b/docs/integrate/get-started/authentication/authentication-guidance.md index 039d343a2c6..3522e06b1aa 100644 --- a/docs/integrate/get-started/authentication/authentication-guidance.md +++ b/docs/integrate/get-started/authentication/authentication-guidance.md @@ -1,52 +1,137 @@ --- -title: Guidance for authentication +title: Choose your authentication method for Azure DevOps titleSuffix: Azure DevOps -description: Guidance for authentication with Azure DevOps +description: Choose the right authentication method for your Azure DevOps integration, with Microsoft Entra ID as the recommended approach. ms.assetid: 15CCEB1E-F42B-4439-8C35-B8A225F5546C ms.subservice: azure-devops-security -ms.topic: conceptual +ms.topic: conceptual +ms.custom: arm2024 +ai-usage: ai-assisted monikerRange: '<= azure-devops' ms.author: chcomley author: chcomley -ms.date: 03/05/2021 +ms.date: 07/14/2025 --- -# Choose the right authentication mechanism +# Choose your authentication method for Azure DevOps [!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. +> [!IMPORTANT] +> **Microsoft Entra ID authentication is recommended** for new applications integrating with Azure DevOps Services. Personal access tokens should be used sparingly and only when Microsoft Entra ID isn't available. -| 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) | +This article helps you choose the most appropriate authentication method for your Azure DevOps integration. Modern authentication approaches like Microsoft Entra ID provide enhanced security and are recommended for new applications. -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). +> [!NOTE] +> OAuth 2.0 and Microsoft Entra ID authentication are only available for Azure DevOps Services, not Azure DevOps Server. For on-premises scenarios, use [Client Libraries](../../concepts/dotnet-client-libraries.md), Windows Authentication, or [personal access tokens](../../../organizations/accounts/use-personal-access-tokens-to-authenticate.md). -#### Enabling IIS Basic Authentication invalidates using PATs for Azure DevOps Server +## Authentication methods by scenario -Learn more about [using IIS Basic Authentication with Azure DevOps on-premises](iis-basic-auth.md). +Choose the appropriate authentication method based on your application type and requirements: -## Frequently asked questions (FAQs) +| Application Type | Description | Example | Recommended Method | Code Samples | +|------------------|-------------|---------|-------------------|-------------| +| **Web/desktop apps** | Interactive applications using current frameworks | React app, .NET desktop app | [Microsoft Entra ID OAuth](./entra-oauth.md) with MSAL | [sample](https://github.com/microsoft/azure-devops-auth-samples/tree/master/ManagedClientConsoleAppSample) | +| **Service/background apps** | Applications running without user interaction | Azure Functions, background services | [Service principals & managed identities](./service-principal-managed-identity.md) | [sample](https://github.com/microsoft/azure-devops-auth-samples/tree/master/ServicePrincipalsSamples) | +| **Legacy client apps** | Existing applications using client libraries | Console apps with Azure DevOps .NET libraries | [Client Libraries](../../concepts/dotnet-client-libraries.md) with OAuth | [sample](https://github.com/Microsoft/vsts-auth-samples/tree/master/ClientLibraryConsoleAppSample) | +| **Headless/CLI apps** | Non-interactive command-line tools | Build scripts, automation tools | [Device Code Flow](./entra-oauth.md) | [sample](https://github.com/Microsoft/vsts-auth-samples/tree/master/DeviceProfileSample) | +| **Azure DevOps extensions** | Extensions running within Azure DevOps | Custom dashboard widgets, work item forms | [VSS Web Extension SDK](https://github.com/Microsoft/azure-devops-extension-sdk) | [sample](../../../extend/develop/add-dashboard-widget.md) | +| **Azure DevOps Server apps** | On-premises Azure DevOps Server integrations | Custom server extensions | [Client Libraries](../../concepts/dotnet-client-libraries.md) or Windows Auth | [sample](https://github.com/Microsoft/vsts-auth-samples/tree/master/ClientLibraryConsoleAppSample) | +| **Personal/ad-hoc scripts** | Quick scripts for personal use | PowerShell scripts, curl commands | [Personal Access Tokens](../../../organizations/accounts/use-personal-access-tokens-to-authenticate.md) | [examples](../../how-to/call-rest-api.md) | -#### 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). +## Getting started recommendations -#### 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. +### For new applications +- **Start with [Microsoft Entra ID authentication](entra-oauth.md)** for the best security and future compatibility. +- Use **service principals or managed identities** for service-to-service scenarios. +- Avoid personal access tokens in production applications. -#### 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. +### For existing applications +- **Plan migration** from personal access tokens to Microsoft Entra ID authentication. +- Consider the [authentication migration timeline](https://devblogs.microsoft.com/devops/reducing-pat-usage-across-azure-devops/) for Azure DevOps improvements. +- Review your current authentication approach against security best practices. -#### 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. +### For Azure DevOps Server +- Use [Client Libraries](../../concepts/dotnet-client-libraries.md) with Windows Authentication when possible. +- Personal access tokens are acceptable for some Azure DevOps Server scenarios. +- Plan for future Azure DevOps Services migration to take advantage of modern authentication. + +## Frequently asked questions + +### Q: Should I use Microsoft Entra ID OAuth or Personal Access Tokens? +A: +**Use Microsoft Entra ID OAuth** for: +- New applications and integrations +- Production workloads requiring robust security +- Applications needing enterprise identity integration +- Long-term projects with compliance requirements + +**Use Personal Access Tokens only for**: +- Personal scripts and ad-hoc tasks +- Legacy applications during migration planning +- Azure DevOps Server scenarios where modern authentication isn't available + +### Q: Should I use service principals or user delegation for authentication? +A: +**Use service principals or managed identities** when: +- Building applications that operate independently (background services, automation) +- Creating apps that don't require user interaction +- Implementing service-to-service communication +- Building CI/CD pipelines or automated workflows + +**Use user delegation (OAuth with user consent)** when: +- Building applications that act on behalf of human users +- Creating interactive apps where users sign in with their own credentials +- Implementing features that require user-specific permissions +- Building apps that need to respect user's individual access rights + +### Q: How do I authenticate with both Azure DevOps Server and Azure DevOps Services? +A: +**Best practice**: Create separate authentication paths: +- **Azure DevOps Services**: Use Microsoft Entra ID OAuth +- **Azure DevOps Server**: Use Client Libraries with Windows Authentication or PATs + +Use the `requestContext` to detect the service type and apply the appropriate authentication method. + +### Q: Why can't my service account access Azure DevOps APIs? +A: +Common issues: +- **Service account not "materialized"**: Service accounts need interactive sign-in permissions or proper Microsoft Entra ID registration +- **Insufficient permissions**: Ensure the service account has appropriate Azure DevOps permissions +- **Authentication method**: Use service principals or managed identities instead of trying to authenticate as a service account + +### Q: How do I migrate from PATs to modern authentication? +A: Do the following steps: +1. **Identify current PAT usage** in your applications +2. **Choose the appropriate modern method**: + - Microsoft Entra ID OAuth for user-delegated scenarios + - Service principals for service-to-service scenarios +3. **Update authentication code** using our [migration samples](https://github.com/microsoft/azure-devops-auth-samples) +4. **Test thoroughly** before removing PAT dependencies +5. **Monitor and validate** the new authentication method + +## Next step + +Choose your authentication implementation: + +**For new applications:** +> [!div class="nextstepaction"] +> [Microsoft Entra ID OAuth](entra-oauth.md) + +**For service applications:** +> [!div class="nextstepaction"] +> [Service principals and managed identities](service-principal-managed-identity.md) + +**For personal scripts:** +> [!div class="nextstepaction"] +> [Personal access tokens](../../../organizations/accounts/use-personal-access-tokens-to-authenticate.md) + +## Related resources + +- [Microsoft Entra ID authentication guide](entra-oauth.md) +- [OAuth 2.0 for Azure DevOps](oauth.md) +- [Azure DevOps Services REST API reference](/rest/api/azure/devops) +- [Azure DevOps .NET Client Libraries](../../concepts/dotnet-client-libraries.md) +- [Authentication code samples](https://github.com/microsoft/azure-devops-auth-samples) +- [Security and identity in Azure DevOps](../../../organizations/security/about-security-identity.md) +- [Azure DevOps data protection overview](../../../organizations/security/data-protection.md) 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..fe075ab84f5 --- /dev/null +++ b/docs/integrate/get-started/authentication/azure-devops-oauth.md @@ -0,0 +1,356 @@ +--- +ms.topic: how-to +title: Use Azure DevOps OAuth 2.0 +description: Learn how to manage existing Azure DevOps OAuth 2.0 applications and plan migration to Microsoft Entra ID OAuth. +ms.subservice: azure-devops-security +ai-usage: ai-assisted +monikerRange: 'azure-devops' +ms.author: chcomley +author: chcomley +ms.date: 07/14/2025 +ms.custom: sfi-image-nochange +--- + +# Use Azure DevOps OAuth 2.0 + +[!INCLUDE [version-eq-azure-devops](../../../includes/version-eq-azure-devops.md)] + +> [!IMPORTANT] +> **Azure DevOps OAuth is deprecated and scheduled for removal in 2026.** This documentation is for existing Azure DevOps OAuth apps only. New app registrations are no longer accepted as of April 2025. +> +> **For new applications**: Use [Microsoft Entra ID OAuth](entra-oauth.md) to integrate with Azure DevOps. +> +> **For existing apps**: Plan your [migration to Microsoft Entra ID OAuth](entra-oauth.md) before 2026. +> +> [Learn more about this deprecation](https://devblogs.microsoft.com/devops/no-new-azure-devops-oauth-apps-beginning-february-2025/). + +This article explains how Azure DevOps OAuth 2.0 works for existing applications and provides guidance for maintaining and migrating your apps. + +## Overview + +Azure DevOps OAuth 2.0 allows applications to access Azure DevOps resources on behalf of users. While this service is deprecated, existing applications continue to function until 2026. + +**Migration recommendation**: Start planning your migration to [Microsoft Entra ID OAuth](entra-oauth.md) to ensure continued service and access to enhanced security features. + +## Prerequisites + +Before working with Azure DevOps OAuth applications: + +| Requirement | Description | +|-------------|-------------| +| **Existing app registration** | An existing Azure DevOps OAuth app (new registrations stopped April 2025) | +| **Azure DevOps organization** | Access to an Azure DevOps Services organization | +| **HTTPS callback URL** | Secure callback URL for your application | +| **Migration plan** | Strategy for migrating to Microsoft Entra ID OAuth before 2026 | + +## Working with existing Azure DevOps OAuth apps + +### 1. Manage your existing app registration + +> [!NOTE] +> New app registrations are no longer accepted. This section applies only to existing registered applications. + +For existing applications, you can view and manage your app settings: + +1. Go to your [Visual Studio profile](https://app.vssps.visualstudio.com/profile/view) to access your app registrations. + +2. Review your [configured scopes](./oauth.md#available-scopes) and ensure they match your application's needs. + +3. Verify your callback URL configuration and update if necessary. + + :::image type="content" source="media/app-page.png" alt-text="Screenshot showing Application settings for your existing app."::: + +4. Plan your migration timeline to Microsoft Entra ID OAuth before the 2026 deprecation deadline. + +### 2. Authorize your app + +The authorization flow remains the same for existing Azure DevOps OAuth apps: + +1. Direct users to the authorization URL with your app parameters: + + ```url + https://app.vssps.visualstudio.com/oauth2/authorize + ?client_id={app ID} + &response_type=Assertion + &state={state} + &scope={scope} + &redirect_uri={callback URL} + ``` + + | Parameter | Type | Description | + |-----------|------|-------------| + | `client_id` | GUID | The ID assigned to your app when it was registered | + | `response_type` | string | Must be `Assertion` | + | `state` | string | A generated string value that correlates the callback with its authorization request | + | `scope` | string | Space-separated scopes registered with the app. See [available scopes](oauth.md#available-scopes) | + | `redirect_uri` | URL | Callback URL for your app. **Must exactly match the URL registered with the app** | + + Example authorization URL: + + ```url + 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 + ``` + + After user authorization, Azure DevOps redirects to your callback URL with the authorization code: + + ```url + https://fabrikam.azurewebsites.net/myapp/oauth-callback + ?code={authorization code} + &state=User1 + ``` + +### 3. Exchange authorization code for access token + +Use the authorization code to request an access token and refresh token: + +#### Request details + +**URL** +```http +POST https://app.vssps.visualstudio.com/oauth2/token +``` + +**Headers** +```http +Content-Type: application/x-www-form-urlencoded +``` + +**Request body** +```http +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} +``` + +**Parameter substitution:** +- `{0}`: URL-encoded client secret from app registration +- `{1}`: URL-encoded authorization code from callback +- `{2}`: Callback URL registered with the app + +#### C# implementation example + +```csharp +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 + +```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 }" +} +``` + +> [!IMPORTANT] +> **Securely store the refresh token** - Access tokens expire quickly, but refresh tokens allow you to get new access tokens without requiring user reauthorization. + +### 4. Use the access token + +Include the access token as a Bearer token in your API requests: + +**Authorization header format:** +```http +Authorization: Bearer {access_token} +``` + +**Example API request:** +```http +GET https://dev.azure.com/myaccount/myproject/_apis/build-release/builds?api-version=3.0 +Authorization: Bearer {access_token} +``` + +### 5. Refresh expired access tokens + +When access tokens expire, use the refresh token to get a new access token: + +**Request:** +```http +POST https://app.vssps.visualstudio.com/oauth2/token +Content-Type: application/x-www-form-urlencoded +Content-Length: 1654 + +client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer&client_assertion={0}&grant_type=refresh_token&assertion={1}&redirect_uri={2} +``` + +**Parameter substitution:** +- `{0}`: URL-encoded client secret +- `{1}`: URL-encoded refresh token +- `{2}`: Callback URL registered with the app + +**Response:** +```json +{ + "access_token": "{ new access token }", + "token_type": "{ type of token }", + "expires_in": "{ time in seconds that the token remains valid }", + "refresh_token": "{ new refresh token }" +} +``` + +> [!IMPORTANT] +> **Update your refresh token** - A new refresh token is issued with each refresh. Store the new token and use it for future refresh operations. + +## Code samples + +You can find working examples in our [Azure DevOps authentication samples repository](https://github.com/Microsoft/vsts-auth-samples/tree/master/OAuthWebSample). + +## Managing app secrets + +> [!IMPORTANT] +> **Secret rotation is critical for security.** Application secrets expire every 60 days and must be rotated to maintain access. + +Azure DevOps OAuth apps support dual secrets to enable zero-downtime rotation: + +### Rotate secrets + +1. **Generate a new secret** in your [Visual Studio profile](https://aex.dev.azure.com/me) or via the [Registration Secret APIs](/rest/api/azure/devops/delegatedauth/registration-secret). + + :::image type="content" source="media/app-page-new-secret.png" alt-text="Screenshot of app page with secondary secret generated."::: + +2. **Confirm the action** in the modal dialog. + + :::image type="content" source="media/secret-regeneration-modal.png" alt-text="Screenshot confirming secret regeneration."::: + +3. **Update your application** to use the new secret before the old one expires. + +4. **Test the new secret** thoroughly before the old secret expires. + +5. **Repeat the process** when the new secret approaches expiration. + +### Emergency secret revocation + +If a secret is compromised: + +1. **Immediately regenerate** the secret in your profile. +2. **Update your application** with the new secret. +3. **Monitor for unauthorized access** in your application logs. + +> [!WARNING] +> Regenerating a secret immediately invalidates the previous secret and all tokens created with it. + +## Delete your app + +> [!WARNING] +> Deleting an app registration immediately breaks all applications using it and invalidates all associated tokens. + +To delete an Azure DevOps OAuth app: + +1. Go to your [Visual Studio profile](https://app.vssps.visualstudio.com/profile/view). +2. Select the correct tenant from the dropdown menu. +3. Find your app under **Applications and services**. +4. Select **Delete** on the application registration page. + + :::image type="content" source="media/azdo-oauth-app-delete.png" alt-text="Screenshot of app metadata page with delete button highlighted"::: + +5. Confirm the deletion in the modal dialog. + +After deletion, the app and all its tokens immediately stop working. + +## Migration planning + +> [!IMPORTANT] +> **Start planning your migration now.** Azure DevOps OAuth is slated for removal in 2026. + +### Migration checklist + +- [ ] **Review [Microsoft Entra ID OAuth documentation](entra-oauth.md)** +- [ ] **Identify all apps using Azure DevOps OAuth** in your organization +- [ ] **Plan migration timeline** allowing adequate testing time +- [ ] **Update application architecture** to support Microsoft Entra ID OAuth +- [ ] **Test migration** in a nonproduction environment +- [ ] **Communicate changes** to users and stakeholders +- [ ] **Complete migration** before 2026 deadline + +### Migration benefits + +**Enhanced security features:** +- Multifactor authentication support +- Conditional Access policies +- Advanced threat protection +- Enterprise identity integration + +**Better developer experience:** +- Modern authentication libraries (MSAL) +- Consistent identity platform across Microsoft services +- Better token management and caching + +**Long-term support:** +- Continued investment and feature development +- Enterprise compliance and governance features + +## Frequently asked questions + +### Q: Can I still create new Azure DevOps OAuth apps? + +A: No. New app registrations stopped in April 2025. Use [Microsoft Entra ID OAuth](entra-oauth.md) for new applications. + +### Q: When will my existing Azure DevOps OAuth app stop working? + +A: Existing apps continue to function until Azure DevOps OAuth is fully deprecated in 2026. Plan your migration well before this deadline. + +### Q: Can I use OAuth with mobile applications? + +A: Azure DevOps OAuth only supports the web server flow and requires secure storage of client secrets, making it unsuitable for mobile apps. Microsoft Entra ID OAuth provides better mobile app support. + +### Q: What should I do if I get an HTTP 400 error when requesting tokens? + +A: Common causes include: +- Incorrect `Content-Type` header (should be `application/x-www-form-urlencoded`) +- Malformed request body parameters +- Invalid or expired authorization code +- Mismatched callback URL + +### Q: Why do I get HTTP 401 errors with OAuth tokens but not with PATs? + +A: Check if your organization administrator disabled **Third-party application access via OAuth** at: +`https://dev.azure.com/{your-org-name}/_settings/organizationPolicy` + +When disabled, OAuth authorization flows work, but API calls return `TF400813: The user "" is not authorized to access this resource.` + +### Q: Can I use localhost for testing? + +A: Yes. Azure DevOps OAuth supports `https://localhost` callback URLs for local development and testing. + +### Q: How do I handle authorization denials and revocations? + +A: Implement proper error handling for: +- **Authorization denial**: No authorization code is returned in the callback +- **Revoked authorization**: API calls return 401 errors; re-request authorization from the user + +### Q: What's the difference between Azure DevOps OAuth and Microsoft Entra ID OAuth? + +A: +- **Azure DevOps OAuth**: Deprecated, Azure DevOps-specific, limited security features +- **Microsoft Entra ID OAuth**: Modern, enterprise-grade, enhanced security, long-term support + +## Next steps + +**For existing applications:** +> [!div class="nextstepaction"] +> [Plan migration to Microsoft Entra ID OAuth](entra-oauth.md) + +**For new applications:** +> [!div class="nextstepaction"] +> [Get started with Microsoft Entra ID OAuth](entra-oauth.md) + +## Related articles + +- [Choose your authentication method](authentication-guidance.md) +- [Migrate to Microsoft Entra ID OAuth](entra-oauth.md) +- [Review OAuth 2.0 scopes for Azure DevOps](oauth.md#available-scopes) +- [Manage app authorizations](../../../organizations/settings/manage-authorizations.md) +- [Explore Azure DevOps REST API reference](/rest/api/azure/devops) +- [Learn about security and identity in Azure DevOps](../../../organizations/security/about-security-identity.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..3607af15985 --- /dev/null +++ b/docs/integrate/get-started/authentication/entra-oauth.md @@ -0,0 +1,47 @@ +--- +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)] + +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. + +This differs from apps that perform actions on-behalf-of themselves. For that, you would use [service principals and managed identities](service-principal-managed-identity.md). + +## 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#available-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) +* [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 + +* Microsoft Entra apps don't natively support Microsoft account (MSA) users for the Azure DevOps resource. 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. +* Azure DevOps' resource identifier: `499b84ac-1321-427f-aa17-267ca6975798` +* Azure DevOps' resource URI: `https://app.vssps.visualstudio.com` +* Use the `.default` scope when requesting a token with all scopes that the app is permissioned for. +* In a previous Azure DevOps OAuth app, you might have use Azure DevOps user identifiers that don't exist in Microsoft Entra. When migrating to 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..e20014d199a --- /dev/null +++ b/docs/integrate/get-started/authentication/entra.md @@ -0,0 +1,48 @@ +--- +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](/entra/fundamentals/whatis) is an identity and access management (IAM) platform that allows companies to manage organization membership and safeguard company resources. Many Azure DevOps enterprise customers choose to [connect their Azure DevOps organization to a Microsoft Entra ID tenant](../../../organizations/accounts/connect-organization-to-azure-ad.md) to support managing the large volume of users in their company and take advantage of other [security features that Microsoft Entra offers](../../../organizations/accounts/access-with-azure-ad.md). + +> [!NOTE] +> Microsoft Entra was once called [Azure Active Directory (Azure AD)](/entra/fundamentals/new-name), so you may still see references to Azure AD across Microsoft products. Active Directory may also be referenced as the on-premises equivalent of Microsoft Entra. + +Once connected, the [Microsoft Identity application platform](/entra/identity-platform/) that sits on top of Microsoft Entra ID can be used to register an application to access Azure tenants and define the permissions needed from Azure resources, including Azure DevOps. + +We support app development for: +* [Microsoft Entra OAuth apps (on-behalf-of users)](entra-oauth.md) +* [Microsoft Entra service principals and managed identities (on-behalf-of itself apps)](service-principal-managed-identity.md) + +## Azure DevOps-based auth vs. Entra-based auth + +Many native Azure DevOps-based authentication (for example, [personal access tokens (PATs)](../../../organizations/accounts/use-personal-access-tokens-to-authenticate.md) or Azure DevOps OAuth apps) were created before Microsoft Entra. 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. Meanwhile, our native tokens sit outside Azure and don't have native support for concepts, like tenants or Conditional Access. + +Tokens issued by each platform are also distinct. Microsoft Entra OAuth apps issue Microsoft Entra tokens, not Azure DevOps access tokens. These tokens can't be used interchangeably on each platform. If you are exploring migrating from Azure DevOps OAuth to Microsoft Entra OAuth, users must reauthorize for the new app. + +## Replace PATs with Microsoft Entra tokens + +Personal access tokens (PATs) are a popular form of Azure DevOps authentication due to their ease of creation and use. However, poor PAT management and storage can result in leaks and unauthorized access to your Azure DevOps organizations. Long-lived or over-scoped PATs increase the risk of damage from a leaked PAT. We encourage users to explore using Microsoft Entra tokens instead of PATs whenever possible. + +### Common PAT alternatives + +Due to their increasing risk, admins are increasingly requesting [security policies that restrict PAT creation](../../../organizations/accounts/manage-pats-with-policies-for-administrators.md). As a result, PATs are becoming a less viable alternative for accessing Azure DevOps programmatically. Outside of migrating any existing app development to the Microsoft Identity platform, we share some common use cases across Azure DevOps that historically rely on PATs and their recommended Microsoft Entra alternative. + +| PAT scenario | Entra alternative | +|------------|------------| +| Authenticate with Git Credential Manager (GCM) | GCM defaults to authenticating with PATs. Set the default credential type to `oauth`. Learn more on our [Git Credential Manager (GCM) page](../../../repos/git/set-up-credential-managers.md) . | +| Authenticate in a build or release pipeline | Use a [service connection with Workload Identity Federation](../../../pipelines/library/connect-to-azure.md#create-an-azure-resource-manager-service-connection-that-uses-workload-identity-federation). | +| Ad-hoc requests to Azure DevOps REST APIs | Issue a [one-off Microsoft Entra token using Azure CLI](../../../cli/entra-tokens.md).  | + +> [!TIP] +> **Have an Azure DevOps PAT scenario with no clear Microsoft Entra token alternative?** Share your scenario in the [Developer Community](https://developercommunity.visualstudio.com/AzureDevOps)! + 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..d0cf86183d3 100644 --- a/docs/integrate/get-started/authentication/oauth.md +++ b/docs/integrate/get-started/authentication/oauth.md @@ -1,307 +1,130 @@ --- ms.topic: how-to -title: Authorize access to REST APIs with OAuth 2.0 -description: Use OAuth 2.0 authentication to get started with the REST APIs for Azure DevOps Services. +title: OAuth 2.0 authentication for Azure DevOps REST APIs +description: Learn how to use OAuth 2.0 authentication with Azure DevOps REST APIs, with Microsoft Entra ID as the recommended approach. ms.assetid: 19285121-1805-4421-B7C4-63784C9A7CFA +ai-usage: ai-assisted ms.subservice: azure-devops-security monikerRange: 'azure-devops' ms.author: chcomley author: chcomley -ms.date: 07/15/2022 +ms.date: 07/14/2025 --- -# Authorize access to REST APIs with OAuth 2.0 +# OAuth 2.0 authentication for Azure DevOps REST APIs [!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. - -> [!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. - -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 it's 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 } -} -``` +Learn how to use OAuth 2.0 to authenticate your applications for Azure DevOps REST API access without requiring users to repeatedly provide credentials. > [!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. +> **Microsoft Entra ID OAuth is the recommended approach** for new applications. Azure DevOps OAuth 2.0 is deprecated and no longer accepts new registrations as of April 2025, with full deprecation planned for 2026. -## 4. Use the access token +## How OAuth 2.0 works with Azure DevOps -To use an access token, include it as a bearer token in the Authorization header of your HTTP request: - -``` -Authorization: Bearer {access_token} -``` +> [!NOTE] +> OAuth 2.0 is only available for Azure DevOps Services, not Azure DevOps Server. For on-premises scenarios, use [Client Libraries](../../concepts/dotnet-client-libraries.md), Windows Authentication, or [personal access tokens](../../../organizations/accounts/use-personal-access-tokens-to-authenticate.md). -For example, the HTTP request to [get recent builds](https://visualstudio.com/api/build-release/builds.md#getalistofbuilds) for a project: +Azure DevOps Services uses the [OAuth 2.0 protocol](https://oauth.net/2/) to authorize applications and generate access tokens for REST API calls. The process involves: -```no-highlight -GET https://dev.azure.com/myaccount/myproject/_apis/build-release/builds?api-version=3.0 -Authorization: Bearer {access_token} -``` +1. **App registration**: Register your application with the OAuth provider +2. **User authorization**: Users grant permission for your app to access their data +3. **Token exchange**: Receive an access token to make API calls +4. **API access**: Use the token for authenticated REST API requests +5. **Token refresh**: Refresh expired tokens to maintain access -## Refresh an expired access token +:::image type="content" source="media/oauth-overview.png" alt-text="OAuth 2.0 authorization flow diagram showing the process from app registration to API access."::: -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. +## OAuth implementation options -### URL - refresh token +Choose the appropriate OAuth implementation based on your application's needs: -```no-highlight -POST https://app.vssps.visualstudio.com/oauth2/token -``` +### Microsoft Entra ID OAuth (Recommended) -### HTTP request headers - refresh token +Microsoft Entra ID OAuth provides the most secure and future-proof authentication method for Azure DevOps applications. Benefits include: -| Header | Value -|-------------------|------------------------------------------------------------------ -| Content-Type | `application/x-www-form-urlencoded` -| Content-Length | Calculated string length of the request body (see the following example) +- **Enterprise integration**: Seamless integration with existing Microsoft Entra ID infrastructure +- **Enhanced security**: Advanced security features including conditional access and multifactor authentication +- **Future support**: Actively maintained and supported platform +- **Unified identity**: Single sign-on experience across Microsoft services -```no-highlight -Content-Type: application/x-www-form-urlencoded -Content-Length: 1654 -``` +**Get started**: Follow our [Microsoft Entra ID OAuth guide](entra-oauth.md) for implementation details and migration guidance. -### HTTP request body - refresh token +### Azure DevOps OAuth (Deprecated) -```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} +> [!WARNING] +> Azure DevOps OAuth is deprecated. New app registrations are no longer accepted as of April 2025, and the service is schedule for full deprecation in 2026. Migrate existing applications to Microsoft Entra ID OAuth. -``` +For existing Azure DevOps OAuth applications: +- Review the [Azure DevOps OAuth guide](./azure-devops-oauth.md) for current implementation details +- Plan migration to Microsoft Entra ID OAuth before 2026 +- [Manage existing app authorizations](../../../organizations/settings/manage-authorizations.md) as needed -Replace the placeholder values in the previous sample request body: +> [!TIP] +> **Migration planning**: Start planning your migration to Microsoft Entra ID OAuth early. Our [migration guide](entra-oauth.md) provides tips and considerations for a smooth transition. -* **{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 +## OAuth scopes -### Response - refresh token +Scopes define what Azure DevOps resources your application can access. Both Microsoft Entra ID OAuth and Azure DevOps OAuth use the same scope definitions. -```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 } -} -``` +### Key scope considerations -> [!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. +- **Principle of least privilege**: Request only the minimum scopes your application needs. +- **Scope inheritance**: Some scopes include others (for example, `vso.code_manage` includes `vso.code_write`). +- **API coverage**: Scopes enable access to REST APIs and select Git endpoints only (SOAP APIs not supported). +- **User consent**: Users must explicitly grant permission for each requested scope. - +### Finding required scopes -## Scopes +To determine what scopes your application needs: +1. Check the API Reference documentation for each endpoint you plan to use. +2. Look for the `scopes` header on each API page. +3. To avoid requesting redundant permissions, consider scope relationships. -> [!IMPORTANT] -> Scopes only enable access to REST APIs and select Git endpoints. SOAP API access isn't supported. +### Available scopes [!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. - -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). - -## 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). - -## 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.` +## Frequently asked questions -### Q: Can I use OAuth with the SOAP endpoints and REST APIs? +### Q: Can I use OAuth with mobile applications? -A: No. OAuth is only supported in the REST APIs at this point. +A: No. Azure DevOps Services only supports the web server flow (authorization code flow), which requires securely storing an app secret. Mobile applications can't securely store secrets, making OAuth unsuitable for mobile scenarios. -### Q: How can I get attachments detail for my work item using Azure DevOps REST APIs? +**Alternative for mobile apps**: Use [personal access tokens](../../../organizations/accounts/use-personal-access-tokens-to-authenticate.md) for mobile application authentication. -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: +### Q: Does OAuth work with all Azure DevOps APIs? -```REST -GET https://dev.azure.com/{organization}/{project}/_apis/wit/workitems/{id} -``` +A: OAuth supports REST APIs and select Git endpoints only. SOAP APIs don't support OAuth authentication. -To get the attachments details, you need to add the following parameter to the URL: +### Q: How do I migrate from Azure DevOps OAuth to Microsoft Entra ID OAuth? -```REST -$expand=all -``` +A: Follow our [Microsoft Entra ID OAuth migration guide](entra-oauth.md), which includes: +- Step-by-step migration instructions +- Code examples and best practices +- Timeline considerations for the deprecation -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: +### Q: What happens to my existing Azure DevOps OAuth app after 2026? -```REST API -$url = https://dev.azure.com/{organization}/{project}/_apis/wit/workitems/434?$expand=all&api-version=5.0 +A: Existing Azure DevOps OAuth apps stop working when the service is fully deprecated in 2026. Plan your migration to Microsoft Entra ID OAuth well before this deadline. -$workItem = Invoke-RestMethod -Uri $url -Method Get -ContentType application/json +## Next step -$split = ($workitem.relations.url).Split('/') +Choose your implementation path: -$attachmentId = $split[$split.count - 1] +**For new applications:** +> [!div class="nextstepaction"] +> [Build with Microsoft Entra ID OAuth](entra-oauth.md) -# Result: 1244nhsfs-ff3f-25gg-j64t-fahs23vfs -``` +**For existing Azure DevOps OAuth apps:** +> [!div class="nextstepaction"] +> [Plan your migration to Microsoft Entra ID](entra-oauth.md) - +**For existing apps that need immediate support:** +> [!div class="nextstepaction"] +> [Azure DevOps OAuth documentation](azure-devops-oauth.md) ## Related articles -* [Choosing the right authentication method](authentication-guidance.md) -* [Default permissions and access for Azure DevOps](../../../organizations/security/permissions-access.md) +- [Authentication guidance overview](authentication-guidance.md) +- [Manage app authorizations](../../../organizations/settings/manage-authorizations.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..c34780c6761 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,164 @@ --- -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 +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. -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. +#### Option 1: Create an application service principal -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) +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. -> [!VIDEO https://www.microsoft.com/en-us/videoplayer/embed/RWWY8q] +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) -#### 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). +#### 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] +For ad-hoc operations, it might be easier to [acquire a one-off Microsoft Entra ID token through the Azure CLI](../../../cli/entra-tokens.md#acquiring-a-token-for-a-service-principal). 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. +### 6. Use the Microsoft Entra ID token to authenticate to Azure DevOps resources -> [!VIDEO https://www.microsoft.com/en-us/videoplayer/embed/RWWL8L] - -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). +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. -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. +> [!VIDEO https://learn-video.azurefd.net/vod/player?id=8397f848-b946-4c30-8d0c-78aa4784a549] -## FAQs +Another example demonstrates how to connect to Azure DevOps using a User Assigned Managed Identity within an Azure Function. -### Q: Why should I use a service principal or a managed identity instead of a PAT? +> [!VIDEO https://learn-video.azurefd.net/vod/player?id=f4a20e00-c2df-49cc-9b86-7454bd84b9ce] -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. +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). -### Q: What are the rate limits on service principals and managed identities? +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) -A: At this time, service principals and managed identities have the same [rate limits](../../concepts/rate-limits.md) as users. +## How service principals differ from users -### Q: Will using this feature cost more? +* 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). -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". +## FAQs -### Q: Can I use a service principal or managed identity with Azure CLI? +#### Q: Why should I use a service principal or a managed identity instead of a PAT? -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. +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). -```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 +You can't use a service principal to create a personal access token. -# To authenticate a service principal with a password or cert: -az login --service-principal -u -p --tenant +#### Q: What are the rate limits on service principals and managed identities? -# To authenticate a managed identity: -az login --identity -``` +A: Service principals and managed identities have the same [rate limits](../../concepts/rate-limits.md) as users. -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 -``` +#### 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 +193,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..9b1508dc4bb 100644 --- a/docs/integrate/get-started/client-libraries/samples.md +++ b/docs/integrate/get-started/client-libraries/samples.md @@ -1,38 +1,31 @@ --- 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/30/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). +The REST examples in this article require the following NuGet packages: -## 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). - -## Other samples -REST examples on this page 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: Using a REST-based HTTP client +### Example: Use 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 +115,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) + -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. +#### Visual Studio sign-in prompt (Microsoft Account or Microsoft Entra backend) for REST services (.NET Framework only) -```cs +Since the .NET Core version doesn't support interactive dialogs, this sample applies only to the .NET Framework version of the clients. + +```csharp public static void MicrosoftAccountRestSample() { // Create instance of VssConnection using Visual Studio sign-in prompt @@ -147,21 +145,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 -##### 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 +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). + +```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..4c14ce0fdd2 100644 --- a/docs/integrate/get-started/rest/samples.md +++ b/docs/integrate/get-started/rest/samples.md @@ -2,37 +2,46 @@ title: REST API samples description: REST API samples for Azure DevOps, including personal access tokens (PATs). ms.assetid: 9E17A266-051F-403F-A285-7F21D9CC52F0 +ai-usage: ai-assisted ms.subservice: azure-devops-ecosystem ms.topic: conceptual ms.custom: devx-track-dotnet monikerRange: '<= azure-devops' ms.author: chcomley author: chcomley -ms.date: 10/06/2020 +ms.date: 06/12/2025 --- -# Get started sample +# REST API samples for Azure DevOps [!INCLUDE [version-lt-eq-azure-devops](../../../includes/version-lt-eq-azure-devops.md)] -## Personal access tokens +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). -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). +For more information, see [Azure DevOps 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). -Get started with these samples and [create a personal access token](../../../organizations/accounts/use-personal-access-tokens-to-authenticate.md). +## Authentication -> [!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. +Authenticate with Azure DevOps when using the REST APIs or .NET Libraries by following these steps: -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: +- **Create a PAT:** + Start with these samples and [create a personal access token (PAT)](../../../organizations/accounts/use-personal-access-tokens-to-authenticate.md). -`` -Authorization: Basic BASE64USERNAME:PATSTRING -`` + [!INCLUDE [use-microsoft-entra-reduce-pats](../../../includes/use-microsoft-entra-reduce-pats.md)] -## REST API +- **Use Basic Authentication with a PAT:** + 1. Convert your PAT to a Base64-encoded string in the format `username:PAT` (the username can be empty). + 2. Add the encoded string to the `Authorization` HTTP header. -See the following example of getting a list of projects for your organization via REST API. + **Example using Basic Authentication with curl:** + + ```bash + curl -u :{yourPAT} https://dev.azure.com/{organization}/_apis/projects?api-version=7.2-preview.1 + ``` + +## GET request samples + +The following C# and curl requests return a JSON response containing the list of all projects in a specified organization: ```cs using System.Net.Http; @@ -65,17 +74,50 @@ using (var client = new HttpClient()) //var value = response.Content.ReadAsStringAsync().Result; } } +``` + + +```curl +-u username:PAT https://dev.azure.com/{organization}/_apis/projects?api-version=6.0 +``` + +## POST request sample + +The following curl request creates a new work item of the "Task" type in a specified project: + +```curl +-u username:PAT -X POST -H "Content-Type: application/json" \ +-d '{"fields": {"System.Title": "New Work Item"}}' \ +https://dev.azure.com/{organization}/{project}/_apis/wit/workitems/$Task?api-version=6.0 +``` + +## PUT request sample + +The following curl request updates an existing work item by changing its state to "In Progress": + +```curl + -u username:PAT -X PATCH -H "Content-Type: application/json-patch+json" \ +-d '[{"op": "add", "path": "/fields/System.State", "value": "In Progress"}]' \ +https://dev.azure.com/{organization}/{project}/_apis/wit/workitems/{id}?api-version=6.0 +``` + +## DELETE request sample + +The following curl request deletes an existing work item from a specified project: +```curl +-u username:PAT -X DELETE \ +https://dev.azure.com/{organization}/{project}/_apis/wit/workitems/{id}?api-version=6.0 ``` ## .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/) -See the following example of getting a list of projects for your organization via .NET Client Libraries. +The following example gets a list of projects for your organization via .NET Client Libraries: ```cs using Microsoft.TeamFoundation.Core.WebApi; @@ -94,7 +136,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..43eb8bbb80e 100644 --- a/docs/integrate/index.md +++ b/docs/integrate/index.md @@ -1,29 +1,30 @@ --- ms.subservice: azure-devops-ecosystem ms.topic: conceptual -title: Integrating custom apps and third party services with Azure DevOps -description: Overview of integrating with Azure DevOps. +title: Building custom apps and third party services with Azure DevOps +description: Overview of building apps with Azure DevOps. 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 +# Build applications [!INCLUDE [version-lt-eq-azure-devops](../includes/version-lt-eq-azure-devops.md)] -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**. +Build custom applications or services that integrate with Azure DevOps to access a user's Azure DevOps resources and perform actions programmatically, instead of needing access through a UI. -Along with interacting with Azure DevOps in your application, you can also integrate with popular third-party services such as Slack or Jenkins. +This can be helpful for writing a script to automate a regular to-do item for your team, or building a product offering for customers that pulls the latest status for Azure DevOps. Consider building with Azure DevOps to help you with: +* [Creating new bugs](./quickstarts/create-bug-quickstart.md) discovered by customers +* [Tracking your team's open work items](./quickstarts/work-item-quickstart.md) on a dashboard -To get started, see: - -- [Create a bug](./quickstarts/create-bug-quickstart.md) -- [Get work items using queries](./quickstarts/work-item-quickstart.md) - - -## Resources - -- [REST API reference](/rest/api/azure/devops/) +To get started, check out the following resources: +* Learn about the different [authentication mechanisms](./get-started/authentication/authentication-guidance.md) available to you. +* [Explore the Microsoft Entra Identity platform](./get-started/authentication/entra.md) when integrating with Azure DevOps to build more secure, enterprise-level applications. +* Read up on the basics to use the [Azure DevOps REST API](./how-to/call-rest-api.md), or +* See if our [client libraries](./concepts/dotnet-client-libraries.md) might be a more suitable alternative to making direct API calls. +* [Integrate with a webhook](../service-hooks/overview.md) to receive and action on events. +* [Develop and publish extensions](../extend/overview.md) on the Visual Studio Marketplace to customize or extend the Azure DevOps platform for your team or customers. +* Review our [app development](./concepts/integration-bestpractices.md) and [security best practices](../organizations/security/security-overview.md) 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..aa3815ad7e3 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: 05/05/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(); - // some error handling - if (ids.Length == 0) + if (ids.Length == 0) + { + return Array.Empty(); + } + + 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( @@ -141,6 +141,75 @@ public class QueryExecutor } ``` +## Troubleshoot + +When you're working with Azure DevOps programmatically, you might encounter issues related to query execution, parameter usage, or method overloads. This section provides guidance on common problems, their causes, and how to resolve them effectively. By understanding these troubleshooting steps, you can ensure smoother integration and avoid runtime errors. + +### Common issues + +- **Improper instantiation of the `Wiql` object**: Ensure the `Wiql` object is properly instantiated and contains a valid query. +- **Incorrect usage of optional parameters**: Verify that optional parameters are being passed correctly, especially if they're null. +- **Invalid query syntax**: Ensure the query in the `Wiql` object is valid and matches the expected format. + +### RuntimeBinderException + +When you work with the `QueryByWiqlAsync` method in Azure DevOps, you might encounter a `RuntimeBinderException`. This exception typically occurs when the arguments passed to the method don't match any of its overloads. Understanding the method's signature and ensuring proper parameter usage can help resolve this issue. + +**Error**: +`RuntimeBinderException`: This exception occurs when the arguments passed to the `QueryByWiqlAsync` method don't match any of the method's overloads. + +**Resolution**: +Ensure that the parameters being passed to the method are of the correct types and in the correct order. The method signature is as follows: + +```csharp +public virtual Task QueryByWiqlAsync( + Wiql wiql, + bool? continueOnError = null, + int? top = null, + object userState = null, + CancellationToken cancellationToken = default(CancellationToken)); + +``` + +**Sample code with correct usage** + +The following code snippet demonstrates the correct usage of the `QueryByWiqlAsync` method, ensuring that the parameters are properly defined: + +```csharp +using Microsoft.TeamFoundation.WorkItemTracking.WebApi; +using Microsoft.TeamFoundation.WorkItemTracking.WebApi.Models; +using System; +using System.Threading.Tasks; +public async Task QueryWorkItemsAsync(WorkItemTrackingHttpClient client) +{ + var wiql = new Wiql() + { + Query = "SELECT [System.Id] FROM WorkItems WHERE [System.TeamProject] = 'YourProjectName'" + }; + + try + { + var result = await client.QueryByWiqlAsync(wiql); + foreach (var workItem in result.WorkItems) + { + Console.WriteLine($"Work Item ID: {workItem.Id}"); + } + } + catch (Microsoft.CSharp.RuntimeBinder.RuntimeBinderException ex) + { + Console.WriteLine($"Error: {ex.Message}"); + } +} +``` + +**Explanation of the code** + +- **Create a `Wiql` object**: The `Wiql` object contains the query to fetch work items. +- **Call `QueryByWiqlAsync`**: Pass the `Wiql` object to the method. +- **Handle exceptions**: Catch the `RuntimeBinderException` and log the error message for debugging. + +By following this approach, you can ensure proper usage of the `QueryByWiqlAsync` method and avoid common issues like `RuntimeBinderException`. + ## Related articles - [Create a bug](./create-bug-quickstart.md) 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..e33ecf7aeeb --- /dev/null +++ b/docs/managed-devops-pools/configure-identity.md @@ -0,0 +1,49 @@ +--- +title: Configure identity +description: Learn how to configure a managed identity for Managed DevOps Pools. +ms.date: 11/18/2024 +ms.custom: sfi-image-nochange +--- + +# 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..c3056a0042d --- /dev/null +++ b/docs/managed-devops-pools/configure-images.md @@ -0,0 +1,472 @@ +--- +title: Configure images +description: Learn how to configure agent images for Managed DevOps Pools. +ms.date: 07/07/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. + +> [!IMPORTANT] +> [!INCLUDE [image-deprecation](./includes/image-deprecation.md)] + +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/ubuntu-24_04-lts/skus/server/versions/latest", + "aliases": [ + "ubuntu-24.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/ubuntu-24_04-lts/skus/server/versions/latest", + "aliases": [ + "ubuntu-24.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/ubuntu-24_04-lts/skus/server/versions/latest", + "aliases": [ + "ubuntu-24.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/ubuntu-24_04-lts/skus/server/versions/latest", + "aliases": [ + "ubuntu-24.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. + +The lifecycle of Azure Pipelines images offered in Managed DevOps Pools follows the lifecycle of the [Microsoft-hosted agent images](../pipelines/agents/hosted.md#software). If an image in Microsoft-hosted agents is deprecated, the corresponding Managed DevOps Pools is also deprecated on a similar timeframe. The version of images available in Microsoft-hosted agents might be slightly different from the version of images available in Managed DevOps Pools for the same image type. + +For more information on Managed DevOps Pools images lifecycle, see [Image lifecycle](#image-lifecycle). + +#### [Azure portal](#tab/azure-portal/) + +When you specify an Azure Pipelines image using the Azure portal, the latest version of the image is always used. + +:::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" + } +] +``` + +You can optionally specify a version in your `wellKnownImageName` setting, for example `"wellKnownImageName": "windows-2022/latest"` or `"wellKnownImageName": "windows-2022/20250427.1.0"`. If you don't specify a version, `latest` is used. + +#### [Azure CLI](#tab/azure-cli/) + +To specify an Azure Pipelines image, provide the predefined 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" + } +] +``` + +You can optionally specify a version in your `wellKnownImageName` setting, for example `"wellKnownImageName": "windows-2022/latest"` or `"wellKnownImageName": "windows-2022/20250427.1.0"`. If you don't specify a version, `latest` is used. + +* * * + +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) | + +> [!IMPORTANT] +> [!INCLUDE [image-deprecation](./includes/image-deprecation.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/ubuntu-24_04-lts/Skus/server/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/ubuntu-24_04-lts/Skus/server/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/resourceGroups/resource_group_placeholder/providers/Microsoft.Compute/galleries/my_images/images/Ubuntu2404" + } +] +``` + +#### [Azure CLI](#tab/azure-cli/) + +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/resourceGroups/resource_group_placeholder/providers/Microsoft.Compute/galleries/my_images/images/Ubuntu2404" + } +] +``` + +* * * + +### 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-24.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-24.04-gen2`. + +```json +"images": [ + { + "resourceId": "/subscriptions/subscription_id_placeholder/Providers/Microsoft.Compute/Locations/eastus/publishers/canonical/artifacttypes/vmimage/offers/ubuntu-24_04-lts/skus/server/versions/latest", + "aliases": [ + "ubuntu-24.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-24.04-gen2`. + +```json +"images": [ + { + "resourceId": "/subscriptions/subscription_id_placeholder/Providers/Microsoft.Compute/Locations/eastus/publishers/canonical/artifacttypes/vmimage/offers/ubuntu-24_04-lts/skus/server/versions/latest", + "aliases": [ + "ubuntu-24.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 24.04 image from the previous example that had an `ubuntu-24.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-24.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 +``` + +## Image lifecycle + +Managed DevOps Pools agent images are retired when the image's operating system reaches the end of its support lifecycle, and images based on older versions of operating systems can be retired when images based on new versions of the operating systems are released. + +* [Azure Pipelines images](#azure-pipelines-images) offers the same images and follows a similar deprecation schedule as [Microsoft-hosted agents](../pipelines/agents/hosted.md#software). +* [Selected marketplace images](#selected-marketplace-images) are typically retired when the image's operating system reaches the end of its support lifecycle. + +### Image deprecation schedule + +* [Azure Pipelines - Windows Server 2019 image deprecation schedule](#azure-pipelines---windows-server-2019-image-deprecation-schedule) +* [Ubuntu 20.04 image deprecation schedule](#ubuntu-2004-image-deprecation-schedule) + +#### Azure Pipelines - Windows Server 2019 image deprecation schedule + +Managed DevOps Pools is removing the **Azure Pipelines – Windows Server 2019** image. + +* Creation of new pools using **Azure Pipelines – Windows Server 2019** will be disabled starting November 1, 2025, but existing pools on these images will continue to run until December 31, 2025. +* On December 31, 2025, use of **Azure Pipelines – Windows Server 2019** image will be disabled. Agents using this image won't provision and pipelines won't run. + +To keep your Managed DevOps Pools running if you use the **Azure Pipelines – Windows Server 2019** image, update to the **Azure Pipelines - Windows Server 2022** image. Alternatively, you can use the Windows Server 2019 image from [Selected marketplace images](./configure-images.md#selected-marketplace-images) or your own [Azure Compute Gallery](./configure-images.md#azure-compute-gallery-images) Windows 2019 image. Note that the marketplace image does not include the pre-installed software found in the Azure Pipelines image. + +#### Ubuntu 20.04 image deprecation schedule + +[Ubuntu 20.04 LTS Standard Support is coming to an end May 31, 2025](https://ubuntu.com/blog/ubuntu-20-04-lts-end-of-life-standard-support-is-coming-to-an-end-heres-how-to-prepare), and Managed DevOps Pools is removing the Ubuntu 20.04 images from [Selected marketplace images](./configure-images.md#selected-marketplace-images) and [Azure Pipelines images](./configure-images.md#azure-pipelines-images). + + * Creation of new pools using Ubuntu 20.04 Selected marketplace images or Azure Pipelines images will be disabled starting June 1, 2025, but existing pools on these images will continue to run until July 1, 2025. + * On July 1, 2025, Pools using Ubuntu 20.04 Selected marketplace images or Azure Pipelines images will be disabled. Agents using these images won't provision and pipelines won't run. + +To keep your Managed DevOps Pools that currently use Ubuntu 20.04 running, update your Ubuntu 20.04 images to Ubuntu 22.04 or 24.04 (recommended). For more information, see [Choose your pool's image](./configure-images.md#choose-your-pools-image). If you have [multiple images](./configure-images.md#use-multiple-images-per-pool-with-aliases) in your pool, [update your aliases](./configure-images.md#configure-image-aliases) for your Ubuntu images so that your pipelines that require Ubuntu will run using the desired image. + +## 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..470417e29e6 --- /dev/null +++ b/docs/managed-devops-pools/configure-networking.md @@ -0,0 +1,201 @@ +--- +title: Configure networking +description: Learn how to configure networking for Managed DevOps Pools. +ms.date: 07/08/2025 +ms.custom: sfi-image-nochange +--- + +# 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're using ARM templates, add a `networkProfile` property in the `fabricProfile` section, 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": { + ... + "fabricProfile": { + "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.) that restrict outbound connectivity, certain endpoints need to be allowlisted in order to fully support Managed DevOps pools. These endpoints are divided into globally required endpoints (necessary on any Managed DevOps pools machine) and endpoints required for certain scenarios. All endpoints are HTTPS, unless otherwise stated. + +* Required Endpoints for Managed DevOps Pool startup - Without allowlisting these endpoints, machines will fail to come online as part of our service, and you will not be able to run pipelines on the Managed DevOps Pool + * `*.prod.manageddevops.microsoft.com` - Managed DevOps Pools endpoint, used to communicate with the Managed DevOps Pools service. + * `rmprodbuilds.azureedge.net` - Used to download the Managed DevOps Pools worker binaries and startup scripts. (The agent portion of the worker binaries is downloaded from `rm-agent.prod.manageddevops.microsoft.com` (formerly downloaded from `agent.prod.manageddevops.microsoft.com`) which is covered by the previous required `*.prod.manageddevops.microsoft.com` entry.) + * `*.queue.core.windows.net` - Worker queue for communicating with Managed DevOps Pools service. +* Required Endpoints for connecting to Azure DevOps - without allowlisting these endpoints, machines may come online and even go to an "allocated" state, but will fail to communicate with ADO as either the VSTS task agent can't connect, or it can't start. + * `download.agent.dev.azure.com` - Azure DevOps agent CDN location, used to download Azure DevOps agent (formerly `vstsagentpackage.azureedge.net` - for more information, see [Edgio CDN for Azure DevOps is being retired](https://devblogs.microsoft.com/devops/important-switching-cdn-providers/)). + * `dev.azure.com` - Required to handle communication with Azure DevOps + * Preparing Linux machines - these endpoints are required to spin up Ubuntu machines, but are not necessary if a pool is only using Windows. As part of setting up the Azure DevOps Task agent, a few required packages are added and an apt-get is run, which will fail without these being allowlisted. + * `azure.archive.ubuntu.com` - Provisioning Linux machines - this is HTTP (port 80), not HTTPS (port 443) + * `www.microsoft.com` - Provisioning Linux machines + * `security.ubuntu.com` - Provisioning Linux machines + * `packages.microsoft.com` - Provisioning Linux machines + * `ppa.launchpad.net` - Provisioning some specific Linux distros + * `dl.fedoraproject.org` - Provisioning certain Linux distros +* Optional, but required for specific Azure DevOps features to work on your pipelines. In the following set, the wildcard can be replaced with the specific Azure DevOps organization hosting your pipeline. For example, if your organization is named `contoso`, you can use `contoso.services.visualstudio.com` instead of `*.services.visualstudio.com`. + * `*.services.visualstudio.com` + * `*.vsblob.visualstudio.com` - Used for Artifacts, both uploading and consuming + * `*.vssps.visualstudio.com` - Used for authentication with Azure DevOps for certain features + * `*.visualstudio.com` + > [!NOTE] + > The previous entries are the minimum domains required. If you have any issues, see [Azure DevOps allowed IP addresses and domain URLs](../organizations/security/allow-list-ip-url.md) for the full list of required domains. +* 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) +* Akamai CDN Delivery IPs: Starting May 1st 2025, Azure DevOps CDN assets are transitioning to a solution served by Akamai and Azure Front Door. Ensure your network has outbound access to Akamai IP ranges. 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 CDN from Edgio retirement FAQ](/previous-versions/azure/cdn/edgio-retirement-faq) + * [Akamai TechDocs - Origin IP Access Control List](https://techdocs.akamai.com/origin-ip-acl/docs/update-your-origin-server) + +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're 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) +* [Azure DevOps allowed IP addresses and domain URLs](../organizations/security/allow-list-ip-url.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..2088a151abd --- /dev/null +++ b/docs/managed-devops-pools/configure-pool-settings.md @@ -0,0 +1,360 @@ +--- +title: Configure pool settings +description: Learn how to configure Managed DevOps Pools settings. +ms.date: 04/28/2025 +ms.custom: sfi-image-nochange +--- + +# 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. + +> [!IMPORTANT] +> [!INCLUDE [image-deprecation](./includes/image-deprecation.md)] + +:::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..a9392861677 --- /dev/null +++ b/docs/managed-devops-pools/configure-scaling.md @@ -0,0 +1,907 @@ +--- +title: Configure scaling +description: Learn the different performance options for Managed DevOps Pools and their impact on agent performance. +ms.date: 07/03/2025 +--- + +# 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. + +For the lifecycle of stateless agents and an explanation on how they are used in Azure DevOps pipelines (including potential delays in allocation), see the following [Lifecycle of agents and potential delays in allocation](#lifecycle-of-agents-and-potential-delays-in-allocation) section. + +#### [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`). + + > [!IMPORTANT] + > If a job is running when the **Max time to live for standby agents** interval expires, the agent won't shut down until the job completes, unless the job takes longer than two days to run. Individual jobs in Managed DevOps Pools can run for a maximum of two days, even if they are running on a standby agent with more than two days configured for **Max time to live for standby agents**. Contact support if your workflow requires running a single job that takes more than two days to complete. + +* **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" + } + } +} +``` + +* * * + +## Lifecycle of agents and potential delays in allocation + +Standby agents using a [Stateless](#stateless-pools) scheme require the Azure Pipelines agent to be installed and configured before transitioning from the [ready](./view-agents.md#status) state to the [allocated](./view-agents.md#status) state and running a pipeline. When Managed DevOps Pools provisions new agents, it attempts to download the latest [Azure Pipelines agent](https://github.com/microsoft/azure-pipelines-agent/releases) in order to have it already downloaded on standby agents before they transition into ready status. Startup, connection, and beginning the job can take anywhere from 10 seconds to a minute depending on the pool's SKU speed, image used, and networking load. Additionally, certain settings in a pipeline job can cause a redownload and running of a different agent, and regressions and rollbacks of the agent can also cause a redownload of the agent. [Ready agents](./view-agents.md#status) will always have a potential delay, as Managed DevOps Pools uses this agent in an "ephemeral" manner, meaning we start and run the task agent one time per job. + +If you are seeing delays in ready agents picking up jobs from Azure DevOps, the following are important to consider: + +* Do you have ready agents? - The most common issue is a misunderstanding of when agents should be preprovisioned. When the number of jobs queued is greater than the standby agent count on a pool, or jobs are queued outside of the pre-provisioning schedule, when the standby agent count is set to be empty, then machines must be spun up from scratch. +* Are you configuring standby agents with multiple images properly? - If you are not specifying which image to use in your pipeline using the [ImageOverride](./demands.md#imageoverride) demand, jobs will be targeting the first image. This means, depending on your scaling settings, you might not have as many agents available as you'd expect as some are allocated to other images. +* Are you using the [ImageVersionOverride](./demands.md#imageversionoverride) in your pipelines? - When you use `ImageVersionOverride` to specify a different image version than what's configured in your [pool settings](./configure-images.md), each agent is started on demand using the specified image version. Standby agents are provisioned using the image versions specified in your [pool's configuration](./configure-images.md), so if you use `ImageVersionOverride`, any standby agents won't match that version and a fresh agent is started. +* Are Proxy/VNet/Firewall settings slowing down your pool? - Potential slowness from any network setting will result in agents taking longer to start the agent and connect it to Azure DevOps. +* Are you overriding the agent version? - By default, Managed DevOps pools will run on the most recent Azure DevOps task agent version. Settings in the Pipeline yaml (such as the [Agent.Version](/azure/devops/pipelines/yaml-schema/pool-demands#agent-variables-as-system-capabilities) demand) and Azure DevOps organization settings can force pipelines to use older versions of the task agent, requiring a redownload once a machine has been allocated. + +## 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..c79760aa34d --- /dev/null +++ b/docs/managed-devops-pools/configure-security.md @@ -0,0 +1,596 @@ +--- +title: Configure security +description: Learn how to configure security settings for Managed DevOps Pools. +ms.date: 07/11/2025 +ms.custom: sfi-image-nochange +--- + +# 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) + +> [!NOTE] +> If you configure your pool with access granted to all projects, the pool is added to the projects for which you have the appropriate permissions. +> +> If you configure your pool with access granted to specific projects, you must have permission to add the pool in all of the designated projects, or the pool creation fails. +> +> To see the permissions required to configure Managed DevOps Pools in your organization and projects, see [Prerequisites - Verify Azure DevOps permissions](./prerequisites.md#verify-azure-devops-permissions). + +### 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": "2025-01-21", + "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. `openAccess` specifies whether Managed DevOps Pools configures [Open access](../pipelines/policies/permissions.md#set-pipeline-permissions-for-an-individual-agent-pool) for the pool during pool creation, `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 open access for pipelines to your pool + +To configure open access for pipelines, you must have the following permissions in addition to the permissions described in [Prerequisites - Verify Azure DevOps permissions](./prerequisites.md#verify-azure-devops-permissions). + +* If you are a [Project collection administrator](../organizations/security/look-up-project-collection-administrators.md), you don't need any additional permissions to configure open access. +* If you are an [organization level pools administrator](../organizations/security/about-security-roles.md#agent-pool-security-roles-organization-or-collection-level), you must also be a [Project administrator](../organizations/security/change-organization-collection-level-permissions.md#add-members-to-the-project-administrators-group) for each project that will be granted access to the Managed DevOps Pool. + +By default, every pipeline definition must be explicitly authorized to run in a self-hosted agent pool (like a Managed DevOps Pool) before it is run for the first time in that pool. + +Azure DevOps provides the following modes for authorizing pipelines to run in an agent pool. + +* **Authorize specific pipelines** - Individually authorize specific pipelines from an Azure DevOps project to run in the pool. This method is the default. +* **Open access** - Configure an agent pool at project level to be available for all pipelines in that project. + +Enable **Allow all pipelines to run on the pool without an approval (open access)** to configure the **Open access** agent pool setting in Azure DevOps when creating the pool. + +> [!NOTE] +> The **Allow all pipelines to run on the pool without an approval (open access)** setting can be configured by Managed DevOps Pools only when the pool is created. After the Managed DevOps Pool is created, you can view and configure [Open access](../pipelines/policies/permissions.md#set-pipeline-permissions-for-an-individual-agent-pool) on the corresponding [agent pool](../pipelines/agents/pools-queues.md) in Azure DevOps for each project that uses the pool. + +#### [Azure portal](#tab/azure-portal/) + +Enable **Allow all pipelines to run on the pool without an approval (open access)** to configure access to the Managed DevOps Pool from all pipelines in the designated projects. + +:::image type="content" source="./media/configure-security/open-access.png" alt-text="Screenshot of configuring open access."::: + +* If **Add pool to all projects** is set to **Yes**, Managed DevOps Pools configures [Open access](../pipelines/policies/permissions.md#set-pipeline-permissions-for-an-individual-agent-pool) for all pipelines in all projects. +* If **Add pool to all projects** is set to **No**, Managed DevOps Pools configures [Open access](../pipelines/policies/permissions.md#set-pipeline-permissions-for-an-individual-agent-pool) for all pipelines only in the listed projects. + +If you enable **Use pool in multiple organizations**, you can specify **Open access** individually for each organization. + +:::image type="content" source="./media/configure-security/open-access-multiple-organizations.png" alt-text="Screenshot of configuring open access for multiple organizations."::: + +#### [ARM template](#tab/arm/) + +> [!NOTE] +> The [Open access](/azure/templates/microsoft.devopsinfrastructure/pools#organizationprofile-objects-1) setting is present when using `api-version 2025-01-21` and higher. + +Organizations are configured in the `organizationProfile` property of the Managed DevOps Pools resource. The following example has two organizations configured. + +* The `fabrikam-tailspin` organization is configured with **Open access** on all projects. +* The `fabrikam-prime` organization is configured for availability with two projects, with **Open access** enabled only on these two projects. + +```json +"organizationProfile": { + "organizations": [ + { + "url": "https://dev.azure.com/fabrikam-tailspin", + "projects": [], + "openAccess": true, + "parallelism": 2 + }, + { + "url": "https://dev.azure.com/fabrikam-prime", + "projects": [ "fabrikam-dev", "fabrikam-test" ], + "openAccess": true, + "parallelism": 2 + } + ], + "permissionProfile": { + "kind": "CreatorOnly" + }, + "kind": "AzureDevOps" +} +``` + +> [!IMPORTANT] +> **Open access** is configured only during Managed DevOps Pool creation. To change the [Open access](../pipelines/policies/permissions.md#set-pipeline-permissions-for-an-individual-agent-pool) setting after pool creation (including adding or removing projects from your Managed DevOps Pool configuration), you must manually configure [Open access](../pipelines/policies/permissions.md#set-pipeline-permissions-for-an-individual-agent-pool) on the corresponding [agent pool](../pipelines/agents/pools-queues.md) in Azure DevOps for each project that uses the pool. + +#### [Azure CLI](#tab/azure-cli/) + +The `openAccess` setting is 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 +``` + +The following `orgaization-profile` example has two organizations configured. + +* The `fabrikam-tailspin` organization is configured with **Open access** on all projects. +* The `fabrikam-prime` organization is configured for availability with two projects, with **Open access** enabled only on these two projects. + +```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 + } + ] + } +} +``` + +> [!IMPORTANT] +> **Open access** is configured only during Managed DevOps Pool creation. To change the Open access setting after pool creation (including adding or removing projects from your Managed DevOps Pool configuration), you must manually configure [Open access](../pipelines/policies/permissions.md#set-pipeline-permissions-for-an-individual-agent-pool) on the corresponding [agent pool](../pipelines/agents/pools-queues.md) in Azure DevOps for each project that uses the pool. + +* * * + +If you try to run a pipeline that is not authorized to access your agent pool, you'll receive an error similar to `This pipeline needs permission to access a resource before this run can continue`. You can resolve this issue either by configuring open access, as described in the previous section, or by [explicitly authorizing the pipeline to run in the agent pool](../pipelines/troubleshooting/troubleshooting.md#this-pipeline-needs-permission-to-access-a-resource-before-this-run-can-continue). + +## 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": "2025-01-21", + "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 agent pool is created at the Azure DevOps organization level, and a project level agent pool is created in each designated project. The **Pool administration permissions** setting specifies which users are granted the administrator permission on the newly created agent pools in Azure DevOps. 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 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). + +- The principal configuring the Key Vault integration settings (if you are configuring the Key Vault settings, then your account) must have the **Key Vault Certificate User** role assignment on the Key Vault where the certificates are stored. + +> [!NOTE] +> As of `api-version 2025-01-21`, 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. +> +> Managed DevOps Pools certificate settings are set at the pool level, and some of the settings are specific for Windows or Linux. If your workflow requires both Linux and Windows images, you may have to divide them into multiple pools if you can't find a common set of certificate settings that work for both Windows and Linux. + +The following settings configure the certificates fetched from your Key Vault. + +- **Certificates** (`observedCertificates`) + + Specify the certificates to be fetched from your Key Vault and installed on all machines in your pool. + +- **Certificate store location** (`certificateStoreLocation`) + + Specify the location to install the certificates on your agent. + + - **Windows agents**: Specify `LocalMachine` or `CurrentUser`. + - **Linux agents**: **Certificate store location** is only support on Ubuntu distributions. Specify the disk path to store the certificates, for example `/var/lib/waagent/Microsoft.Azure.KeyVault/app1`. + For Ubuntu distributions, if you specify the trusted store location, for example `/usr/local/share/ca-certificates`, the certificate is added to that certificate store as root. For more information, see [Install a root CA certificate in the trust store](https://documentation.ubuntu.com/server/how-to/security/install-a-root-ca-certificate-in-the-trust-store/index.html). + +- **Certificate store name** (`certificateStoreName`) + + - **Windows agents**: Specify the name of the certificate store, either `My` (local certificate store - default if no name is specified) or `Root` (trusted root location). + - **Linux agents**: This setting isn't used on Linux agents. + +- **Exportable private keys** (`keyExportable`) + + Whether the key of the certificates is exportable. The default is `false`. + +#### [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. + +> [!NOTE] +> The `osProfile.certificateStoreName` property is only available in `apiVersion 2025-01-21` and later. + +```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": "2025-01-21", + "location": "eastus", + "properties": { + ... + "fabricProfile": { + "sku": {...}, + "images": [...], + "osProfile": { + "secretsManagementSettings": { + "certificateStoreLocation": "LocalMachine", + "certificateStoreName": "Root", + "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 its first 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 [Azure 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 [Key Vault virtual machine 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..739c5d0cd54 --- /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: 06/23/2025 +--- + +# 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**. If you're using an ARM template or Azure CLI script to configure your storage, omit the drive letter parameter if you don't want a drive letter. | + +## 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..615004c535a --- /dev/null +++ b/docs/managed-devops-pools/demands.md @@ -0,0 +1,131 @@ +--- +title: Configure demands +description: Learn how to configure demands for Managed DevOps Pools. +ms.date: 05/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). + +#### [Windows](#tab/windows/) + +The default work folder for Windows agents is typically on the **D:\\** drive and can be referenced in your pipeline by using the `Agent.WorkFolder` [predefined variable](/azure/devops/pipelines/build/variables). + +In the following example, `WorkFolder` is set to an [attached data disk](./configure-storage.md?tabs=windows#use-the-data-disk-for-your-agent-working-directory) that is assigned the letter `F`. + +```yml +pool: + name: fabrikam-managed-pool # Name of Managed DevOps Pool + demands: + - WorkFolder -equals f:\custom-work-folder +``` + +#### [Linux](#tab/linux/) + +The default work folder for agents is typically **/mnt** for Linux, and can be referenced in your pipeline by using the `Agent.WorkFolder` [predefined variable](/azure/devops/pipelines/build/variables). + +In the following example, `WorkFolder` is set to an [attached data disk](./configure-storage.md?tabs=linux#use-the-data-disk-for-your-agent-working-directory). + +```yml +pool: + name: fabrikam-managed-pool # Name of Managed DevOps Pool + demands: + - WorkFolder -equals /mnt/storage/sdc/custom-work-folder +``` + +* * * + +## 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-24.04-gen2` alias. + +```yml +pool: + name: fabrikam-dev-pool # Name of Managed DevOps Pool + demands: + - ImageOverride -equals ubuntu-24.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 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. + +> [!IMPORTANT] +> When you use `ImageVersionOverride` to specify a different image version than what's configured in your [pool settings](./configure-images.md), each agent is started on demand using the specified image version. +> +> [Standby agents](./configure-scaling.md#standby-agent-mode) are provisioned using the image versions specified in your [pool's configuration](./configure-images.md), so if you use `ImageVersionOverride`, any standby agents won't match that version and a fresh agent is started. + +Configure the `ImageVersionOverride` demand in the `demands` section of your pipeline. The following example specifies an `ImageVersionOverride` of `20250427.1.0`. + +```yml +pool: + name: fabrikam-dev-pool # Name of Managed DevOps Pool + demands: + - ImageVersionOverride -equals 20250427.1.0 +``` + +> [!TIP] +> If you think a pipeline is failing due to an image update, follow the procedure in [Troubleshooting - Check to see if there has been an image update](./troubleshooting.md#check-to-see-if-there-has-been-an-image-update). + +## 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..27fabd45663 --- /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/24_04-lts-gen2/24.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..a7b85e9afac --- /dev/null +++ b/docs/managed-devops-pools/features-timeline.md @@ -0,0 +1,64 @@ +--- +title: Features timeline and roadmap +description: Learn about new features in Managed DevOps Pools. +ms.date: 06/20/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. + +* **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 June 2025.** + +* [Ubuntu 20.04 LTS Standard Support is coming to an end May 31, 2025](https://ubuntu.com/blog/ubuntu-20-04-lts-end-of-life-standard-support-is-coming-to-an-end-heres-how-to-prepare), and Managed DevOps Pools is removing the Ubuntu 20.04 images from [Selected marketplace images](./configure-images.md#selected-marketplace-images) and [Azure Pipelines images](./configure-images.md#azure-pipelines-images). For more information, see [Managed DevOps Pools image lifecycle](./configure-images.md#image-lifecycle). **Planned for June 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). **Planned for June 2025.** + +* **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 July 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 August 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.** + +## May 2025 + +* **Shorter time for agent allocation**: The Managed DevOps Pools team made updates to shorten the startup time for [standby agents](./configure-scaling.md#standby-agent-mode) (**Fresh agent every time** setting). For more information, see [Lifecycle of agents and potential delays in allocation](./configure-scaling.md#lifecycle-of-agents-and-potential-delays-in-allocation). + +## 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](../pipelines/agents/pools-queues.md#pipeline-permissions) so that administrators don't need to explicitly authorize each pipeline. For more information, see [Configure open access for pipelines to your pool](./configure-security.md#configure-open-access-for-pipelines-to-your-pool). + +* **Trusted root certificates**: Managed DevOps Pools added 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). + +## 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/image-deprecation.md b/docs/managed-devops-pools/includes/image-deprecation.md new file mode 100644 index 00000000000..95a10791808 --- /dev/null +++ b/docs/managed-devops-pools/includes/image-deprecation.md @@ -0,0 +1,11 @@ +--- +ms.topic: include +ms.date: 06/05/2025 +--- + +The following images are being deprecated in Managed DevOps Pools. + +* Azure Pipelines - Windows Server 2019 +* Ubuntu 20.04 + +For more information, see [Managed DevOps Pools image deprecation schedule](../configure-images.md#image-deprecation-schedule). 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..0a24c921f8a 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-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..4f52094c37a 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..03c0b40ad61 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..07983c499c7 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..f83a4155a05 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/open-access-multiple-organizations.png b/docs/managed-devops-pools/media/configure-security/open-access-multiple-organizations.png new file mode 100644 index 00000000000..b953b468959 Binary files /dev/null and b/docs/managed-devops-pools/media/configure-security/open-access-multiple-organizations.png differ diff --git a/docs/managed-devops-pools/media/configure-security/open-access.png b/docs/managed-devops-pools/media/configure-security/open-access.png new file mode 100644 index 00000000000..26af5fef114 Binary files /dev/null and b/docs/managed-devops-pools/media/configure-security/open-access.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-agent-pools-security.png b/docs/managed-devops-pools/media/prerequisites/organization-agent-pools-security.png new file mode 100644 index 00000000000..a19367bead0 Binary files /dev/null and b/docs/managed-devops-pools/media/prerequisites/organization-agent-pools-security.png differ diff --git a/docs/managed-devops-pools/media/prerequisites/organization-agent-pools.png b/docs/managed-devops-pools/media/prerequisites/organization-agent-pools.png new file mode 100644 index 00000000000..6530fe91d01 Binary files /dev/null and b/docs/managed-devops-pools/media/prerequisites/organization-agent-pools.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/project-agent-pools-security.png b/docs/managed-devops-pools/media/prerequisites/project-agent-pools-security.png new file mode 100644 index 00000000000..6ebe1885de8 Binary files /dev/null and b/docs/managed-devops-pools/media/prerequisites/project-agent-pools-security.png differ diff --git a/docs/managed-devops-pools/media/prerequisites/project-agent-pools.png b/docs/managed-devops-pools/media/prerequisites/project-agent-pools.png new file mode 100644 index 00000000000..2b7939bb236 Binary files /dev/null and b/docs/managed-devops-pools/media/prerequisites/project-agent-pools.png differ diff --git a/docs/managed-devops-pools/media/prerequisites/project-settings.png b/docs/managed-devops-pools/media/prerequisites/project-settings.png new file mode 100644 index 00000000000..a546b9b4317 Binary files /dev/null and b/docs/managed-devops-pools/media/prerequisites/project-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/media/troubleshooting/view-pipeline-run-image-version.png b/docs/managed-devops-pools/media/troubleshooting/view-pipeline-run-image-version.png new file mode 100644 index 00000000000..8dec2d44bd1 Binary files /dev/null and b/docs/managed-devops-pools/media/troubleshooting/view-pipeline-run-image-version.png differ diff --git a/docs/managed-devops-pools/media/troubleshooting/view-pipeline-run-job-details.png b/docs/managed-devops-pools/media/troubleshooting/view-pipeline-run-job-details.png new file mode 100644 index 00000000000..cac96629344 Binary files /dev/null and b/docs/managed-devops-pools/media/troubleshooting/view-pipeline-run-job-details.png differ diff --git a/docs/managed-devops-pools/media/troubleshooting/view-pipeline-runs-compare-image-versions.png b/docs/managed-devops-pools/media/troubleshooting/view-pipeline-runs-compare-image-versions.png new file mode 100644 index 00000000000..70a7cdd64fa Binary files /dev/null and b/docs/managed-devops-pools/media/troubleshooting/view-pipeline-runs-compare-image-versions.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..e6c6236bc6d --- /dev/null +++ b/docs/managed-devops-pools/migrate-from-scale-set-agents.md @@ -0,0 +1,58 @@ +--- +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: 05/21/2025 +ms.topic: overview +ms.custom: peer-review-program +#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 + +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 the virtual machines that run 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. + + +## 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.md) | Pricing is the same for Managed DevOps Pools and Scale set agents. You pay a fixed monthly cost for [Azure DevOps Services self-hosted parallel jobs](./pricing.md#azure-devops-services-parallel-job-pricing), combined with the cost of the [Azure services used by your pool](./pricing.md#azure-services-pricing). See [Managed DevOps Pools pricing](./pricing.md) for more information. | Same as Managed DevOps Pools pricing | +| Virtual machine hosting | Agents run on an Azure subscription owned and managed by Microsoft. For more information, see [Microsoft Managed DevOps Pools architecture overview](./architecture-overview.md) | Agents run on your Azure subscription | +| [Standby agent schedule](./configure-scaling.md#standby-agent-mode) | Provides [flexible scheduling options](./configure-scaling.md#standby-agent-mode) to configure the number of standby agents available at different times as well as an [automatic standby agent option](./configure-scaling.md#automatic) | 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](./configure-images.md#use-multiple-images-per-pool-with-aliases) | Support for [multiple images in your pool](./configure-images.md) | Supports only a single image | +| [Quota](./prerequisites.md#view-your-quotas) | 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](./configure-networking.md) | Support for running in a private network or joining your existing virtual network | Support for joining an existing virtual network or creating a new one | +| [Image support](./configure-images.md) | [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](./configure-security.md#key-vault-configuration) | 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](./configure-security.md#use-pool-in-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](./configure-scaling.md#stateless-pools) | 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](./configure-scaling.md#stateful-pools) | Supported | Supported | +| Spot Virtual Machine support | [On product roadmap](./features-timeline.md) | Not supported | +| Containers | [On product roadmap](./features-timeline.md) | Not supported | +| BCDR | Not yet planned, but will be prioritized [based on customer feedback](https://developercommunity.visualstudio.com/AzureDevOps) | [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 similar behavior as your Azure virtual machine scale set agent pool by mapping the scale set agent pool settings to their Managed DevOps Pools equivalent. + +| Scale set agents setting | Managed DevOps Pools equivalent 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) | + +## See also + +* [Managed DevOps Pools pricing](./pricing.md) +* [Manage cost and performance of Managed DevOps Pools](./manage-costs.md) +* [Azure Virtual Machine Scale Set agents](../pipelines/agents/scale-set-agents.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..5d83bca8940 --- /dev/null +++ b/docs/managed-devops-pools/monitor-pool.md @@ -0,0 +1,140 @@ +--- +title: Monitor +description: Learn how to view the health of your Managed DevOps Pools. +ms.date: 04/25/2025 +--- + +# 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. | +| `WorkerSetupFailed`, `UnableToDownloadWorkerCheckNetwork`, `UnableToDownloadWorkerCheckNetwork[]` | [The Network infrastructure is blocking access to one of the prerequisite endpoints.](./configure-networking.md#restricting-outbound-connectivity) | +| `UnableToDownloadWorkerCheckNetwork_TLSIssue` | [TLS Handshake failed when contacting prerequisite endpoints.](./configure-networking.md#restricting-outbound-connectivity) | + + +## 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..61cffda4662 --- /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: 07/03/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. Contact support if your workflow requires running a single job that takes more than two days to complete. +* 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..a79ecc90f36 --- /dev/null +++ b/docs/managed-devops-pools/prerequisites.md @@ -0,0 +1,307 @@ +--- +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: 07/11/2025 +ms.custom: sfi-image-nochange +--- + +# 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 the [contributor or owner role](/azure/role-based-access-control/built-in-roles) on your subscription is assigned to your account. + + +#### [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` + +> [!NOTE] +> Certain Azure regions require customers to go through a [request process in order to gain access](/troubleshoot/azure/general/region-access-request-process), and your subscription may not be granted the default quota. See [View your quotas](#view-your-quotas) to view the quotas for your subscription, and if you don't have quota for your desired virtual machine sizes, see [request a quota adjustment](#request-a-quota-adjustment) for instructions on how to request quota. + +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 the following permissions in your Azure DevOps organization. + +| Permission | Description | +|------------|-------------| +| [Azure DevOps organization member](#verify-membership-in-the-azure-devops-organization) | You must be a member of the Azure DevOps organization where you want to create Managed DevOps Pools. | +| [Organization level agent pools administrator](#organization-level-agent-pools-administrator) | You must have agent pool **Administrator** permissions at the organization level in the Azure DevOps organization where you want to create Managed DevOps Pools. | +| [Project level agent pools administrator or creator](#project-level-agent-pools-administrator-or-creator) | You must have **Administrator** or **Creator** agent pool permissions at the project level for each project in which you want to make your Managed DevOps Pool available to pipelines. | + +### Verify membership in the Azure DevOps organization + +You must be a member of the Azure DevOps organization before the permissions in this section can be granted to your account. + +> [!TIP] +> If you are currently working in the Azure DevOps organization, for example using Azure Boards, working with Azure Repos, or using Azure Pipelines, you are already a member of the Azure DevOps organization, and you can skip this step. + +To verify your membership in the Azure DevOps organization, go to `https://dev.azure.com/{organization}/_settings/users`, replacing `{organization}` with the name of your Azure DevOps organization. + +* If you are denied access to the page, you are not a member of the Azure DevOps organization. You must be [added as a member](../organizations/accounts/add-organization-users.md#add-users-to-your-organization) by an administrator of the Azure DevOps organization. +* If you can access the page, review the user list and verify that you are a member of the Azure DevOps organization. If you don't see your account listed, you must be [added as a member](../organizations/accounts/add-organization-users.md#add-users-to-your-organization) by an administrator of the Azure DevOps organization. + +### Organization level agent pools administrator + +You must have Organization level agent pools **Administrator** permissions for each organization where you want to create Managed DevOps Pools. + +You can be directly granted the **Organization-level agent pools administrator** permission by a [Project Collection Administrator](../organizations/security/look-up-project-collection-administrators.md) or another **Organization-level Agent pools administrator**, and you are granted this permission automatically if you are a [Project Collection Administrator](../organizations/security/look-up-project-collection-administrators.md). + +To check your agent pools permissions at the organization level: + +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** > **Security**. + + :::image type="content" source="./media/prerequisites/organization-agent-pools.png" alt-text="Screenshot of Organization level agent pools list."::: + + You can also go directly to organization level agent pools security settings by going to `https://dev.azure.com/{organization name}/_settings/agentpools`, and choosing **Security**. + +1. View the list of user permissions for the organization level agent pools scope. In this example no specific users have been added, so only Project collection administrators have permission to create pools or assign users to this role. + + :::image type="content" source="./media/prerequisites/organization-agent-pools-security.png" alt-text="Screenshot of Organization level agent pools security page."::: + +1. If you need to create Managed DevOps Pools in this organization, ask a Project collection administrator, or an administrator listed here, to choose **Add**, add you as an administrator, and choose **Save**. For more information, see [Set agent pool security in Azure Pipelines](../pipelines/policies/permissions.md#set-agent-pool-security-in-azure-pipelines). + + > [!TIP] + > If the **Add** button is disabled, you don't have permission to create Managed DevOps Pools in this organization. + > + > If the **Add** button is enabled, you do have permission to create Managed DevOps Pools in this organization. + +### Project level agent pools administrator or creator + +You must have Project level agent pools **Administrator** or **Creator** permissions for each project in which you want to make your Managed DevOps Pool available to pipelines. + + * If you create your Managed DevOps Pool with **Add pool to all projects** set to **Yes**, Managed DevOps Pools will configure the pool to be available in all projects for which you have the **Administrator** or **Creator** permission. To use the pool in other projects, you can manually add the pool to the other projects after you are granted the **Administrator** or **Creator** permission for those projects. + * If you provide a list of projects when creating your Managed DevOps Pool, you must have the **Administrator** or **Creator** permission for every listed project or else pool creation fails. + +You can be directly granted the **Administrator** or **Creator** permission by a [Project Collection Administrator](../organizations/security/look-up-project-collection-administrators.md), a [Project administrator](../organizations/security/change-organization-collection-level-permissions.md#add-members-to-the-project-administrators-group), or another **Project-level agent pools administrator**. You are granted the **Administrator** role automatically if you are a [Project Collection Administrator](../organizations/security/look-up-project-collection-administrators.md) or [Project administrator](../organizations/security/change-organization-collection-level-permissions.md#add-members-to-the-project-administrators-group). + +To check your agent pools permissions at the project level: + +1. Go to the Azure DevOps portal and sign in to your Azure DevOps organization (`https://dev.azure.com/{your-organization}`), go to the project where you want to run pipelines using your Managed DevOps Pool, and choose **Project settings**. + + :::image type="content" source="./media/prerequisites/project-settings.png" alt-text="Screenshot of Project settings button."::: + +1. Go to **Pipelines** > **Agent pools** > **Security**. + + :::image type="content" source="./media/prerequisites/project-agent-pools.png" alt-text="Screenshot of Project level agent pools list."::: + + You can also go directly to project level agent pools security settings by going to `https://dev.azure.com/{organization name}/{project name}/_settings/agentqueues`, and choosing **Security**. + +1. View the list of user permissions for the project level agent pools scope. In this example no specific users have been added, so only the default project level group administrators (and Project collection administrators) have permission to create pools at the project level, or assign users to this role. + + :::image type="content" source="./media/prerequisites/project-agent-pools-security.png" alt-text="Screenshot of Project level agent pools security page."::: + +1. If you need to create Managed DevOps Pools for use in this Project, ask a Project collection administrator, a Project administrator (or anyone in one of the listed administrator groups), or an administrator listed here, to choose **Add**, add you as an **Administrator** or **Creator**, and choose **Save**. For more information, see [Set agent pool security in Azure Pipelines](../pipelines/policies/permissions.md#set-agent-pool-security-in-azure-pipelines). + + > [!TIP] + > If the **Add** button is enabled, you have permission to create Managed DevOps Pools for use in this project. + > + > If the **Add** button is disabled, you don't have permission to create Managed DevOps Pools for use in this project, unless you have the **Creator** permission, in which case your name (or the name of a group for which you are a member) would be listed in the **User permissions** list as having the **Creator** permission. + +## 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..f5fe10c7429 --- /dev/null +++ b/docs/managed-devops-pools/pricing.md @@ -0,0 +1,55 @@ +--- +title: Managed DevOps Pools pricing +description: Learn how pricing is calculated for your Managed DevOps Pools. +ms.date: 04/28/2025 +ms.topic: concept-article +ms.custom: peer-review-program +#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. +--- + +# Managed DevOps Pools pricing + +Managed DevOps Pools pricing is a combination of the cost of the Azure services your pool uses, like compute, storage, and data egress, and the standard Azure DevOps Services parallel jobs pricing for self-hosted agents. This article describes how to estimate and project the costs for your Managed DevOps Pools. + +## Azure services pricing + +The primary cost for Managed DevOps Pools is the cost of the Azure services that your pool uses, like compute, storage, and data egress, which are billed at the standard Azure pricing rates. For more information, 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). + +## Azure DevOps Services parallel job pricing + +The secondary cost for Managed DevOps Pools is the Azure DevOps parallel jobs cost. In Azure DevOps, a parallel job refers to the compute capacity to run a [pipeline job](../pipelines/process/phases.md). Managed DevOps Pools agents are considered to be self-hosted agents, and run using self-hosted parallel jobs. Azure DevOps Services provides organizations one free self-hosted parallel job with unlimited minutes. If you want the capacity to run five concurrent pipeline jobs on Managed DevOps Pools agents, you must pay for four additional self-hosted parallel jobs. + + The Azure DevOps parallel jobs portion of the Managed DevOps Pools cost is a fixed monthly cost based on the number of purchased self-hosted parallel jobs, and does not increase or decrease based on the time your agents are provisioned or the duration of your pipeline jobs. For more information, see: + +* [Configure and pay for parallel jobs](../pipelines/licensing/concurrent-jobs.md?tabs=self-hosted) +* The [Azure DevOps pricing](https://azure.microsoft.com/pricing/details/devops/azure-devops-services/) section for **Self-hosted** agents. + +> [!NOTE] +> The Azure DevOps self-hosted parallel jobs count for your organization determines how many self-hosted agents can run jobs concurrently in your Azure DevOps organization, including your pipelines running on Managed DevOps Pools agents. The parallel jobs count is different than the Managed DevOps Pools [Maximum agents](./configure-pool-settings.md#maximum-agents) setting, which configures the maximum number of agents that your pool makes available to run pipelines. If you set **Maximum agents** to **5**, ensure that you have at least five self-hosted parallel jobs available in your organization. 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 self-hosted parallel job, you can only run a single pipeline at a time. + +## Estimating cost + +A basic formula for estimating monthly Managed DevOps Pools cost is to combine fixed costs like [Azure DevOps Services parallel job pricing](#azure-devops-services-parallel-job-pricing), non-hourly Azure services costs like [Azure Storage pricing](https://azure.microsoft.com/pricing/details/storage/blobs/), [Managed Disks pricing](https://azure.microsoft.com/pricing/details/managed-disks/), and [standard data egress charges](https://azure.microsoft.com/pricing/details/bandwidth/), and hourly Azure services cost, primarily [Virtual Machines pricing](https://azure.microsoft.com/pricing/details/virtual-machines/linux/), which is typically the largest portion of your monthly Managed DevOps Pools cost. + +To estimate the number of hours used when projecting the hourly Azure services cost, 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 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 Virtual machine 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 your selected Azure VM size is 12 cents an hour, and you are projected to run 4000 hours of jobs, your projected monthly cost for hourly services 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..2400b540b6c --- /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: 04/30/2025 +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. For more information see [This pipeline needs permission to access a resource before this run can continue](../pipelines/troubleshooting/troubleshooting.md#this-pipeline-needs-permission-to-access-a-resource-before-this-run-can-continue). + +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..75f6babe21f --- /dev/null +++ b/docs/managed-devops-pools/quickstart-azure-cli.md @@ -0,0 +1,331 @@ +--- +title: Create a Managed DevOps Pool using Azure CLI +description: Learn how to create a Managed DevOps Pool using Azure CLI. +ms.date: 04/30/2025 +ms.topic: quickstart +ms.custom: peer-review-program +#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 + +* Managed DevOps Pools prerequisites + + Before completing the steps in this article, you must 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. + +* Azure CLI prerequisites + + * If you want to run the Azure CLI commands on your local machine, see the [Azure CLI installation instructions](/cli/azure/install-azure-cli). If you already have Azure CLI installed, run `az version` to check your version. The Azure CLI extension for Managed DevOps Pools requires Azure CLI version 2.57.0 or higher. If your Azure CLI is lower than 2.57.0, run `az upgrade`. For more information, see [How to update the Azure CLI](/cli/azure/update-azure-cli). + * If you want to use [Azure Cloud Shell](https://portal.azure.com/#cloudshell/) through your browser, follow the instructions in [Get started with Azure Cloud Shell ephemeral sessions](/azure/cloud-shell/get-started/ephemeral) to register the **Microsoft.CloudShell** namespace. You only need to register the namespace once per subscription. + + The following examples use bash, so if you are using Azure Cloud Shell, choose **Bash** when starting Azure Cloud Shell. + +## 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 to the Azure CLI. 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. + + ```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 REGION=EastUS2 + export RANDOM_ID="$(openssl rand -hex 3)" + export RESOURCE_GROUP_NAME="myManagedDevOpsPoolGroup$RANDOM_ID" + export POOL_NAME="mdpPool$RANDOM_ID" + export DEV_CENTER_NAME="mdpDevCenter$RANDOM_ID" + export DEV_CENTER_PROJECT_NAME="mdpDevCenterProject$RANDOM_ID" + + # Echo the generated resource names + echo $REGION + echo $RESOURCE_GROUP_NAME + echo $POOL_NAME + echo $DEV_CENTER_NAME + echo $DEV_CENTER_PROJECT_NAME + ``` + +## 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. Run the following command, which installs the Azure CLI `devcenter` extension if it's not installed, and updates it to the latest version if it's 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 named **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-24.04" + ], + "buffer": "*", + "wellKnownImageName": "ubuntu-24.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-24.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. Run the following command, which installs the Azure CLI `mdp` extension if it's not installed, and updates it to the latest version if it's 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-pool`, 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. For more information see [This pipeline needs permission to access a resource before this run can continue](../pipelines/troubleshooting/troubleshooting.md#this-pipeline-needs-permission-to-access-a-resource-before-this-run-can-continue). + +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..c41e2e3256e --- /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: 04/30/2025 +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. For more information see [This pipeline needs permission to access a resource before this run can continue](../pipelines/troubleshooting/troubleshooting.md#this-pipeline-needs-permission-to-access-a-resource-before-this-run-can-continue). + +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..7fdc864f5ff --- /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 event 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..8a171751df3 --- /dev/null +++ b/docs/managed-devops-pools/troubleshooting.md @@ -0,0 +1,128 @@ +--- +title: Troubleshoot Managed DevOps Pools issues +description: Learn how to troubleshoot common issues with Managed DevOps Pools. +ms.topic: how-to +ms.date: 05/21/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. + +## Pipeline fails to successfully complete + +### Check to see if there has been an image update + +If your pipelines begin to fail after an image update, you can temporarily configure your pipelines to use the previous image version. You can configure your failing pipelines to use the previous image version on a per-pipeline basis, or you can configure the previous image version for all pipelines in your Managed DevOps Pool that use that image. + +To see whether your pipelines are failing due to an image version change, compare the image version on a failed pipeline run with the image version from the last successful pipeline run. + +1. [Go to your pipeline](../pipelines/create-first-pipeline.md#view-and-manage-your-pipelines) and review the [pipeline run history](../pipelines/create-first-pipeline.md#view-pipeline-details) for your pipeline. + + :::image type="content" source="./media/troubleshooting/view-pipeline-runs-compare-image-versions.png" alt-text="Screenshot of pipeline runs."::: + +1. [View the run details](../pipelines/create-first-pipeline.md#view-pipeline-run-details) for the two pipeline runs you want to compare, and choose the pipeline job to view diagnostic information abut that job. If your pipeline has multiple jobs, choose the job that runs using your Managed DevOps Pool. + + :::image type="content" source="./media/troubleshooting/view-pipeline-run-job-details.png" alt-text="Screenshot of pipeline run details."::: + +1. Choose **Initialize job**, and retrieve the image version from the **Current image version** section. + + :::image type="content" source="./media/troubleshooting/view-pipeline-run-image-version.png" alt-text="Screenshot of pipeline run image version."::: + +If the image versions are different between the recent failed pipeline run and the previous successful run, the failure may be caused by an image update. You have two choices to temporarily revert to the previous image version while you troubleshoot the root cause. +* To run only the failing pipeline using the previous image version, add an `ImageVersionOverride` demand to your pipeline to specify the previous version. For more information, see [ImageVersionOverride](./demands.md#imageversionoverride). +* To update the pool settings so that all pipelines using the image run using the previous version, update your [Image settings](./configure-images.md) and specify the desired version. + * If you're using [Azure Pipelines images](./configure-images.md#azure-pipelines-images), you must use [ARM templates](./configure-images.md?tabs=arm#azure-pipelines-images) or [Azure CLI](./configure-images.md?tabs=azure-cli#azure-pipelines-images) to specify the version, since Azure Pipelines images configured using the [Azure portal](./configure-images.md?tabs=azure-portal#azure-pipelines-images) always uses the latest version. + * If you're using [Selected marketplace images](./configure-images.md#selected-marketplace-images) or [Azure Compute Gallery images](./configure-images.md#azure-compute-gallery-images), you can specify the version using the Azure portal as well as ARM templates and Azure CLI. + +Managed DevOps Pools keeps the past 20 images available for Selected marketplace images and the past 10 images available for Azure Pipelines images. Past versions of Azure Compute Gallery images are maintained by the owners of those Azure Compute Galleries. + +## 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..9b2010c703e 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: @@ -47,33 +47,15 @@ landingContent: links: - text: Create a custom pipelines task url: ../extend/develop/add-build-task.md?toc=/azure/devops/marketplace-extensibility/toc.json - - title: Integrate applications - linkLists: - - linkListType: overview - links: - - text: Integration overview - url: ../integrate/index.md?toc=/azure/devops/marketplace-extensibility/toc.json - - linkListType: how-to-guide - links: - - text: Authorize access to REST APIs with OAuth 2.0 - url: ../integrate/get-started/authentication/oauth.md?toc=/azure/devops/marketplace-extensibility/toc.json - - text: Authorize access with service principals and managed identities - url: ../integrate/get-started/authentication/service-principal-managed-identity.md?toc=/azure/devops/marketplace-extensibility/toc.json - - text: Authenticate access with personal access tokens - url: ../organizations/accounts/use-personal-access-tokens-to-authenticate.md?toc=/azure/devops/marketplace-extensibility/toc.json - - linkListType: reference - links: - - text: .NET client libraries - url: ../integrate/concepts/dotnet-client-libraries.md - title: Integrate with Slack or Microsoft Teams 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: @@ -87,3 +69,9 @@ landingContent: url: ../service-hooks/services/teams.md?toc=/azure/devops/marketplace-extensibility/toc.json - text: Create a service hook with WebHooks url: ../service-hooks/services/webhooks.md?toc=/azure/devops/marketplace-extensibility/toc.json + - title: Building applications on Azure DevOps + linkLists: + - linkListType: overview + links: + - text: Learn about building applications + url: ../integrate/index.md?toc=/azure/devops/marketplace-extensibility/toc.json diff --git a/docs/marketplace-extensibility/toc.yml b/docs/marketplace-extensibility/toc.yml index 355044404e9..f61755aee5d 100644 --- a/docs/marketplace-extensibility/toc.yml +++ b/docs/marketplace-extensibility/toc.yml @@ -2,6 +2,8 @@ href: index.yml - name: Extensions overview href: ../extend/overview.md?toc=/azure/devops/marketplace-extensibility/toc.json +- name: Authenticating with Azure DevOps + href: ../integrate/get-started/authentication/authentication-guidance.md?toc=/azure/devops/marketplace-extensibility/toc.json - name: Get started items: - name: Install an extension @@ -13,20 +15,9 @@ - name: Manage extension permissions displayName: grant, publish, update, settings, admin href: ../marketplace/grant-permissions.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 PATs - href: ../organizations/accounts/use-personal-access-tokens-to-authenticate.md?toc=/azure/devops/marketplace-extensibility/toc.json - - name: Authenticate with OAuth 2.0 - 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: Manage high privilege extensions + displayName: permission, administrator, privilege, extension, scope, Marketplace + href: ../marketplace/manage-high-privilege-extensions.md?toc=/azure/devops/marketplace-extensibility/toc.json - name: Develop extensions items: - name: Get started @@ -105,9 +96,6 @@ - name: Add a dashboard widget displayName: create, contribution, REST, API, configure href: ../extend/develop/add-dashboard-widget.md?toc=/azure/devops/marketplace-extensibility/toc.json - - name: Add a chart - displayName: create, configure, HTML, extension, manifest - href: ../extend/develop/add-chart.md?toc=/azure/devops/marketplace-extensibility/toc.json - name: Call a REST API displayName: client, service, API href: ../extend/develop/call-rest-api.md?toc=/azure/devops/marketplace-extensibility/toc.json @@ -124,13 +112,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 +183,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 @@ -203,57 +191,7 @@ - name: Troubleshoot and FAQs displayName: issue, activity, debug, subscription, terminal, transient, failure href: ../service-hooks/troubleshoot.md?toc=/azure/devops/marketplace-extensibility/toc.json -- name: Integrate applications - items: - - name: Integrate applications overview - href: ../integrate/index.md?toc=/azure/devops/marketplace-extensibility/toc.json - - name: Get started - items: - - name: Create a bug - displayName: client, library, code, project, PAT - href: ../integrate/quickstarts/create-bug-quickstart.md?toc=/azure/devops/marketplace-extensibility/toc.json - - name: Query work items - displayName: get, fetch, queries, rest, api - href: ../integrate/quickstarts/work-item-quickstart.md?toc=/azure/devops/marketplace-extensibility/toc.json - - name: Best practices - displayName: integrate, procedure, correct, effective - href: ../integrate/concepts/integration-bestpractices.md?toc=/azure/devops/marketplace-extensibility/toc.json - - name: Service hooks - displayName: information, what, are - href: ../integrate/concepts/service-hooks.md?toc=/azure/devops/marketplace-extensibility/toc.json - - name: Create service hooks subscriptions programmatically - displayName: rest, api, build, complete, code - href: ../service-hooks/create-subscription.md?toc=/azure/devops/marketplace-extensibility/toc.json - - name: Call REST API - displayName: integrate, instance, collection - href: ../integrate/how-to/call-rest-api.md?toc=/azure/devops/marketplace-extensibility/toc.json - - name: REST API versioning - displayName: applications, services, usage - href: ../integrate/concepts/rest-api-versioning.md?toc=/azure/devops/marketplace-extensibility/toc.json - - name: .NET client libraries - displayName: integrate, developer, package, rest, api - href: ../integrate/concepts/dotnet-client-libraries.md?toc=/azure/devops/marketplace-extensibility/toc.json - - name: Cross-origin resource sharing - displayName: CORS, JavaScript, code, Oauth, PATs - href: ../integrate/concepts/cross-origin-resource-sharing.md?toc=/azure/devops/marketplace-extensibility/toc.json - - name: Samples - items: - - name: .NET - displayName: sample, c#, library, REST, authenticate - href: ../integrate/get-started/client-libraries/samples.md?toc=/azure/devops/marketplace-extensibility/toc.json - - name: .NET (Legacy) - displayName: SOAP, authenticate, PAT, Azure, Visual, Studio - href: ../integrate/get-started/client-libraries/soapSamples.md?toc=/azure/devops/marketplace-extensibility/toc.json - - name: REST API Samples - displayName: PATs, personal, access, token, client, libraries - href: ../integrate/get-started/rest/samples.md?toc=/azure/devops/marketplace-extensibility/toc.json - - name: Create a PR status server - displayName: pull, request, web, configure, service, hook - href: ../repos/git/create-pr-status-server.md?toc=/azure/devops/marketplace-extensibility/toc.json - - name: Use Azure Functions to create custom branch policies - displayName: pull, request, PR, Repos, event, service, hook - href: ../repos/git/create-pr-status-server-with-azure-functions.md?toc=/azure/devops/marketplace-extensibility/toc.json -- name: Microsoft Teams & Slack +- name: Microsoft Teams & Slack extensions items: - name: Azure Boards with Slack href: ../boards/integrations/boards-slack.md?toc=/azure/devops/marketplace-extensibility/toc.json @@ -267,10 +205,10 @@ href: ../pipelines/integrations/slack.md?toc=/azure/devops/marketplace-extensibility/toc.json - name: Azure Pipelines with Microsoft Teams href: ../pipelines/integrations/microsoft-teams.md?toc=/azure/devops/marketplace-extensibility/toc.json +- name: Building Azure DevOps applications + href: ../integrate/index.md?toc=/azure/devops/dev-resources/toc.json - name: Reference items: - - name: REST API reference overview - href: ../integrate/rest-api-overview.md - name: Rate limits href: ../integrate/concepts/rate-limits.md - name: Deprecation of WIT & Test client OM @@ -279,16 +217,16 @@ href: ../integrate/concepts/migration-guide.md - name: .NET client libraries reference href: /dotnet/api/index?view=azure-devops-dotnet&preserve-view=true - - name: Azure DevOps Services REST API >> + - name: Azure DevOps Services REST API Reference >> href: /rest/api/azure/devops/ -- name: Reference (Archived) - items: - - name: Client reference >> - href: /previous-versions/azure/devops/extend/reference/client/client-services?view=tfs-2017&preserve-view=true - - name: REST APIs for TFS 2015, 2017, and 2018 >> - href: /previous-versions/azure/devops/integrate/previous-apis/overview - - name: Extension Debugging in a Browser >> - href: /previous-versions/azure/devops/extend/test/debug-in-browser + - name: Reference (Archived) + items: + - name: Client reference >> + href: /previous-versions/azure/devops/extend/reference/client/client-services?view=tfs-2017&preserve-view=true + - name: REST APIs for TFS 2015, 2017, and 2018 >> + href: /previous-versions/azure/devops/integrate/previous-apis/overview + - name: Extension Debugging in a Browser >> + href: /previous-versions/azure/devops/extend/test/debug-in-browser - name: Resources items: - name: How to buy Azure DevOps CALs >> @@ -310,4 +248,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..eab691796c4 100644 --- a/docs/marketplace/install-extension.md +++ b/docs/marketplace/install-extension.md @@ -1,48 +1,62 @@ --- 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' +ms.custom: + - engagement-fy23 + - devx-track-azurecli + - sfi-image-nochange --- # Install extensions [!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 +77,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 +158,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 +253,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 +289,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 +347,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 +404,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 +463,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..d3274c94963 --- /dev/null +++ b/docs/marketplace/manage-high-privilege-extensions.md @@ -0,0 +1,87 @@ +--- +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/23/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 behavior. +--- + +# Manage high privilege scopes, pipeline decorators, and unpublished extensions + +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. + +## What are high privilege scopes and high privilege extensions? + +### High privilege scopes + +Scopes determine in general which resources an extension can access and the operations permitted to perform on those resources. Extensions might use multiple scopes. + +As for what is defined as a high privilege scope, it's a scope that is overly permissive. + +For example a high privilege scope can: +- Read, update, and delete your source code +- Read, write, and manage your identities and groups +- Create, read, update, and delete your projects + +For the full list of scopes, including the high privilege scopes, see the [Manifest reference](../extend/develop/manifest.md#scopes). + +### High privilege extensions + +High privilege extensions make use of one or more high privilege scopes. As high privilege extensions can access sensitive resources and perform critical operations, it's essential to evaluate them carefully to ensure they align with your organization's security and operational standards. + +When it comes to any extension, and even more a high privilege extension, consider the following elements: +- **Trusted 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**. + +We recommend that you only install, update, or use extensions if you trust their code and their publishers. + +Microsoft runs virus scans on each new and updated version of an extension; yet this feature only highlights in the user interface whether a specific extension uses high privilege scopes. For more information on the virus scans, 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) + +## Manage extensions with high privilege scopes + +If you identify an extension with high privilege scopes, assess whether the called scopes from the extension are essential for your use case. If the extension's functionality doesn't justify the scopes, we recommend not installing or using the extension to safeguard your Azure DevOps organization. + +> [!div class="mx-imgBorder"] +> ![Screenshot showing high privilege scope details for the extension.](media/high-privilege-extensions/details-scopes.png) + +The Visual Studio Marketplace for Azure DevOps extensions provides similar indications to those extensions shown in the admin page for high privilege scopes. So you can also identify high privilege scopes flagged in the [Azure DevOps Visual Studio Marketplace](https://marketplace.visualstudio.com/azuredevops) before the extension is installed in your organization. + +When you select any extension and especially an extension with high privilege scopes, think critically 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) + +## Use pipeline decorators safely + +[Pipeline decorators](../extend/develop/add-pipeline-decorator.md) are private extensions that modify and enhance all pipelines within your organization, they're also classified as high privilege extensions. 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) + +## Discontinue use of unpublished extensions + +Beyond high privilege extensions, the extension's administration page visually indicates whether an extension has been unpublished by its publisher. + +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. + +Additionally, 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 enables you to programmatically identify extensions that are unpublished from the Visual Studio Marketplace. And for example, you can build your own process of detecting and managing unpublished extensions within your Azure DevOps organization. + +## Related articles + +- [Secure your Azure DevOps environment](../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-org-settings-s172.png b/docs/media/settings/open-org-settings-s172.png deleted file mode 100644 index 16a25135cda..00000000000 Binary files a/docs/media/settings/open-org-settings-s172.png and /dev/null differ diff --git a/docs/media/settings/open-organization-settings-2025.png b/docs/media/settings/open-organization-settings-2025.png new file mode 100644 index 00000000000..9ddb5b9999a Binary files /dev/null and b/docs/media/settings/open-organization-settings-2025.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..3f43b3ae6eb --- /dev/null +++ b/docs/migrate/migration-prepare-test-run.md @@ -0,0 +1,285 @@ +--- +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 +ms.custom: sfi-image-nochange +--- + +# 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..4d3f6353e80 --- /dev/null +++ b/docs/migrate/migration-test-run.md @@ -0,0 +1,575 @@ +--- +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 +ms.custom: sfi-image-nochange +--- + +# 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..31d17ed9b73 --- /dev/null +++ b/docs/migrate/migration-validate.md @@ -0,0 +1,201 @@ +--- +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) +- [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..361f27723f4 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)] +This article discusses controlling access to your organization using Microsoft Entra ID. [Connecting your organization to Microsoft Entra ID](connect-organization-to-azure-ad.md) enhances security and simplifies user management. -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. +## 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 Azure AD controls access to Azure DevOps + -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. +## How Microsoft Entra ID controls access to Azure DevOps -Without Azure AD, you're solely responsible for controlling organization access. All users must sign in with Microsoft accounts. +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. + +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 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) +> [!div class="nextstepaction"] +> [Connect your organization to Microsoft Entra ID](./connect-organization-to-azure-ad.md) + ## 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) +* [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-microsoft-entra-id.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..c45326af5f7 100644 --- a/docs/organizations/accounts/admin-revoke-user-pats.md +++ b/docs/organizations/accounts/admin-revoke-user-pats.md @@ -1,61 +1,82 @@ --- 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' --- -# Revoke personal access tokens for organization users +# Revoke organization user's personal access tokens (for admins) [!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 +> [!TIP] +> Create or revoke your own PAT on your [Personal access token page](use-personal-access-tokens-to-authenticate.md#revoke-a-pat). + +[!INCLUDE [use-microsoft-entra-reduce-pats](../../includes/use-microsoft-entra-reduce-pats.md)] +## Why revoke user PATs? -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). +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. -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). +## Prerequisites + +[!INCLUDE [prerequisites-pca-only](../../includes/prerequisites-pca-only.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) +- [Use personal access tokens to authenticate](use-personal-access-tokens-to-authenticate.md) +- [Manage personal access tokens with policies (for admins)](manage-pats-with-policies-for-administrators.md) +- [Authenticate to Azure DevOps with Microsoft Entra](../../integrate/get-started/authentication/entra.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..634791aaf05 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: 07/02/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..f878ca194d5 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,77 @@ --- -title: Restrict new organization creation, Azure Active Directory tenant policy +title: Restrict new organization creation 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.assetid: +ai-usage: ai-assisted ms.topic: conceptual ms.author: chcomley author: chcomley -ms.date: 05/13/2022 +ms.date: 07/01/2025 monikerRange: 'azure-devops' +ms.custom: + - sfi-image-nochange --- -# Restrict organization creation via Azure AD tenant policy +# Restrict organization creation [!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](../security/look-up-azure-devops-administrator.md) role in Microsoft Entra ID. | ## 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 +After you enable the policy, you can customize its behavior by creating an allowlist for exceptions and customizing the error message users see when they can't create organizations. + ### 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-microsoft-entra-id.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..8bc29ee1394 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 +title: Change application connection and 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). +description: Manage security policies for accessing organization through 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: 06/06/2025 monikerRange: 'azure-devops' --- @@ -16,79 +15,52 @@ 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 users and 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**|
        • Org-level policies: [Project Collection Administrator](../security/look-up-project-collection-administrators.md)
        • Tenant-level policies: [Azure DevOps Administrator](../security/look-up-azure-devops-administrator.md)
        | [!INCLUDE [manage-policies](../../includes/manage-policies.md)] +## Restrict authentication methods -## Application connection policies +To allow seamless access to your organization without repeatedly prompting for user credentials, applications can use authentication methods, like [OAuth](../../integrate/get-started/authentication/oauth.md), [SSH](../../repos/git/use-ssh-keys-to-authenticate.md), and [personal access token (PATs)](use-personal-access-tokens-to-authenticate.md). By default, all existing organizations allow access for all authentication methods. -To access your organization without asking for user credentials multiple times, applications often use the following authentication methods: +You can limit access to these authentication methods by disabling the following 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 affect [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. +- Tenant admins can [**restrict global personal access token creation**](manage-pats-with-policies-for-administrators.md#restrict-creation-of-global-pats-tenant-policy), [**restrict full-scoped personal access token creation**](manage-pats-with-policies-for-administrators.md#restrict-creation-of-full-scoped-pats-tenant-policy), and [**enforce maximum personal access token lifespan**](manage-pats-with-policies-for-administrators.md#set-maximum-lifespan-for-new-pats-tenant-policy) through tenant-level policies on the _Microsoft Entra_ settings page. Add Microsoft Entra users or groups to exempt them from these policies. +- Organization admins can [**restrict personal access token creation**](manage-pats-with-policies-for-administrators.md#restrict-personal-access-token-creation-organization-policy) in their respective organizations. Subpolicies allow admins to permit the creation of packaging-only PATs or the creation of any-scope PATs to allowlisted Microsoft Entra users or groups. -* [**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. +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. -* [**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: + - * 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/) +## Conditional Access policy support on Azure DevOps -By default, your organization allows access for all authentication methods. +[Conditional Access (CA) in Azure DevOps](conditional-access-policies.md) is enforced through Microsoft Entra ID and supports both interactive (web) and non-interactive (client credential) flows, validating policies like MFA, IP restrictions, and device compliance during sign-in and periodically via token checks. -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 this method. Any application that previously had access will get authentication errors and no longer have access to your organization. +## Policies by Level -To remove access for PATs, you must [revoke them](use-personal-access-tokens-to-authenticate.md). +| Policy | Org-level | Tenant-level | +|--------------|-------------| +| [**Third-party application access via OAuth**](#restrict-authentication-methods) | ✅ | | +| [**SSH authentication**](#restrict-authentication-methods) | ✅ | | +| [**Log audit events**](../audit/azure-devops-auditing.md) | ✅ | | +| [**Restrict personal access token creation**](manage-pats-with-policies-for-administrators.md#restrict-personal-access-token-creation-organization-policy) | ✅ | | +| [**Allow public projects**](../projects/make-project-public.md) | ✅ | | +| [**Additional protections when using public package registries**](https://devblogs.microsoft.com/devops/changes-to-azure-artifact-upstream-behavior/) | ✅ | | +| [**Enable IP Conditional Access policy validation on non-interactive flows**](conditional-access-policies.md) | ✅ | | +| [**External guest access**](add-external-user.md) | ✅ | | +| [**Allow team and project administrators to invite new users**](../security/restrict-invitations.md) | ✅ | | +| [**Request access** allows users to request access to the organization with a provided internal URL](disable-request-access-policy.md) | ✅ | | +| [**Allow Microsoft to collect feedback from users**](../security/data-protection.md#data-privacy) | ✅ | | +| [**Restrict organization creation**](azure-ad-tenant-policy-restrict-org-creation.md) | | ✅ | +| [**Restrict global personal access token creation**](manage-pats-with-policies-for-administrators.md#restrict-creation-of-global-pats-tenant-policy) | | ✅ | +| [**Restrict full-scoped personal access token creation**](manage-pats-with-policies-for-administrators.md#restrict-creation-of-full-scoped-pats-tenant-policy)| | ✅ | +| [**Enforce maximum personal access token lifespan**](manage-pats-with-policies-for-administrators.md#set-maximum-lifespan-for-new-pats-tenant-policy) | | ✅ | -## Conditional access policies - -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 -- 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 multi-factor authentication or further checks to gain access, or block access altogether. - -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. - -Azure DevOps can also perform more CAP validation once you're signed in and navigating through Azure DevOps. - -* 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. - -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. - -#### 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. - - -## 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 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) diff --git a/docs/organizations/accounts/change-azure-ad-connection.md b/docs/organizations/accounts/change-azure-ad-connection.md index 45c583710d0..3906d47b5bc 100644 --- a/docs/organizations/accounts/change-azure-ad-connection.md +++ b/docs/organizations/accounts/change-azure-ad-connection.md @@ -1,40 +1,48 @@ --- -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. +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' +ms.custom: + - engagement-fy23 + - sfi-image-nochange --- -# 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 +50,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-microsoft-entra-id.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/conditional-access-policies.md b/docs/organizations/accounts/conditional-access-policies.md new file mode 100644 index 00000000000..4d017450474 --- /dev/null +++ b/docs/organizations/accounts/conditional-access-policies.md @@ -0,0 +1,76 @@ +--- +title: Conditional Access policies on Azure DevOps +titleSuffix: Azure DevOps Services +description: Set up Microsoft Entra Conditional Access policies to grant or restrict access to tenant resources +ms.subservice: azure-devops-organizations +ms.assetid: 2fdfbfe2-b9b2-4d61-ad3e-45f11953ef3e +ms.topic: how-to +ms.author: chcomley +author: chcomley +ms.date: 06/27/2025 +monikerRange: 'azure-devops' +--- + +# Set up Conditional Access policies on Azure DevOps + +Microsoft Entra ID lets tenant admins control which users can access Microsoft resources using [Conditional Access policies](/azure/active-directory/conditional-access/overview). Admins set specific conditions users must meet to gain access, such as: + +- Membership in a specific Microsoft Entra security group +- Location or network requirements +- Use of a particular operating system +- Use of a managed and enabled device + +Based on these conditions, you can grant access, require more checks like multifactor authentication, or block access entirely. Learn more about [Conditional Access policies](/azure/active-directory/active-directory-conditional-access) in the Microsoft Entra documentation. + +## Prerequisites + +## Create a Conditional Access policy for Azure DevOps + +| Category | Requirements | +|--------------|-------------| +|**Permissions**| You must be at least a **Conditional Access Administrator** to set up a Conditional Access policy in your tenant. Learn more in the ["Create a Conditional Access policy" Entra docs](/entra/identity/authentication/tutorial-enable-azure-mfa#create-a-conditional-access-policy). | + +1. Go to the [Azure portal](https://portal.azure.com) and find the **"Microsoft Entra Conditional Access"** service. +2. Select **"Policies"** on the right sidebar. +3. Select the **"+ New policy"** button. Provide the policy a name. +5. For the **"Target resources"** assignments, toggle **"Select resources"** and add the _"Microsoft Visual Studio Team Services"_ resource (resource id: 499b84ac-1321-427f-aa17-267ca6975798) to the list of target resources. +6. Configure other settings as desired. +7. Select **Save** to apply this new policy. + + :::image type="content" source="./media/setup-ado-cap.png" alt-text="Screenshot showing how to add Azure DevOps as a target resource on a new Conditional Access policy in Microsoft Entra portal."::: + +### Conditional Access behavior on web + +When you sign in to the web portal of a Microsoft Entra ID-backed organization, Microsoft Entra ID validates all Conditional Access policies set by tenant administrators. After [modernizing our web authentication stack to use Microsoft Entra tokens](https://devblogs.microsoft.com/devops/full-web-support-for-conditional-access-policies-across-azure-devops-and-partner-web-properties/), Azure DevOps now enforces Conditional Access policy validation on all interactive (web) flows. + +- Meet sign-in policies when using [Personal Access Tokens (PATs)](use-personal-access-tokens-to-authenticate.md) on REST API calls that rely on Microsoft Entra. +- Remove Azure DevOps as a resource from the Conditional Access policy, which prevents Conditional Access policies from applying. +- Enforce MFA policies on web flows only; block access for non-interactive flows if users don't meet a Conditional Access policy. + +### IP-based conditions + +| Category | Requirements | +|--------------|-------------| +|**Permissions**| You must be an [Project Collection Administrator](../security/look-up-project-collection-administrators.md) to enable this policy.
      | + +If the **IP Conditional Access policy validation on non-interactive flows** organization policy is enabled on the **Organization Settings** page, Azure DevOps checks IP fencing policies on non-interactive flows, such as when you use a PAT to make a REST API call. + +Azure DevOps supports IP-fencing Conditional Access policies for both IPv4 and IPv6 addresses. If Conditional Access policies block your IPv6 address, ask your tenant administrator to update the policy to allow your IPv6 address. Also, consider including the IPv4-mapped address for any default IPv6 address in all Conditional Access policy conditions. + +If users access the Microsoft Entra sign-in page from a different IP address than the one used to access Azure DevOps resources (which can happen with VPN tunneling), review your VPN configuration or networking setup. Make sure your tenant administrator includes all relevant IP addresses in the Conditional Access policies. + +### Azure Resource Manager audience + +> [!NOTE] +> These changes will go into effect starting July 28, 2025. Learn more in [our blog post](https://devblogs.microsoft.com/devops/removing-azure-resource-manager-reliance-on-azure-devops-sign-ins/). + +Azure DevOps doesn't depend on the Azure Resource Manager (ARM) resource (`https://management.azure.com`) when you sign in or refresh Microsoft Entra access tokens. Previously, Azure DevOps required the ARM audience during sign-in and token refresh flows. This requirement meant that administrators had to allow all Azure DevOps users to bypass ARM Conditional Access policies to ensure access. + +If you previously set up a Conditional Access policy for Azure Resource Manager or the associated [Windows Azure Service Management API application](/entra/identity/conditional-access/concept-conditional-access-cloud-apps#windows-azure-service-management-api), this policy no longer covers Azure DevOps sign-ins. Set up a new Azure DevOps Conditional Access policy for continued coverage of Azure DevOps. + +The following groups still require continued access to ARM. You may want to consider adding them as exclusions to any ARM or Windows Azure Service Management API Conditional Access policies. +- **Billing administrators** need access to ARM to set up billing and access subscriptions. +- **Service Connection creators** require access to ARM for ARM role assignments and updates to managed service identities (MSIs). + +## Related articles +* [Change application connection & security policies for your organization](change-application-access-policies.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..039bb981a7d 100644 --- a/docs/organizations/accounts/connect-organization-to-azure-ad.md +++ b/docs/organizations/accounts/connect-organization-to-azure-ad.md @@ -1,124 +1,79 @@ --- -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' +ms.custom: sfi-image-nochange --- -# 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-microsoft-entra-id.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..4c6f34ec686 100644 --- a/docs/organizations/accounts/delete-your-organization.md +++ b/docs/organizations/accounts/delete-your-organization.md @@ -1,54 +1,54 @@ --- 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. +description: Learn how to permanently delete an Azure DevOps organization, what happens to users and data, recovery options, and administrator deletion capabilities for Microsoft Entra ID administrators. ms.subservice: azure-devops-organizations ms.assetid: 82433ad3-d665-4a11-95b7-82178f493fb5 -ms.topic: conceptual +ai-usage: ai-assisted +ms.topic: how-to ms.author: chcomley author: chcomley -ms.date: 04/16/2020 +ms.date: 07/02/2025 monikerRange: 'azure-devops' +#customer intent: As an Azure DevOps administrator, I want to permanently delete an organization I no longer need while understanding the impact on users, data recovery options, and administrator deletion capabilities. --- -# Delete your organization +# Delete an organization [!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}```). +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 **Overview** > **Delete**. ![Screenshot of organization settings, with Overview and Delete highlighted](media/delete-organization/organization-overview-settings.png) @@ -61,7 +61,18 @@ permissions. [How do I find the Project Collection Administrators?](../security/ [Need help?](faq-configure-customize-organization.yml#get-support) -Your organization is deleted. +The organization is deleted. + +## Delete an organization - for Microsoft Entra ID administrators + +If your organization is connected to Microsoft Entra ID, **Global Administrators** and **Application Administrators** in your Microsoft Entra ID tenant can view and manage Azure DevOps organizations connected to their tenant. These administrators can delete organizations even if they weren't the original creator. Do the following steps, for Microsoft Entra ID administrators: + +1. Sign in to the [Azure portal](https://portal.azure.com) as a Global Administrator or Application Administrator. +2. Go to **Microsoft Entra ID** > **Manage** > **Enterprise applications** +3. Search for and select **Azure DevOps**. +4. View connected Azure DevOps organizations under **Users and groups** or **Properties**. +5. Access the Azure DevOps organization using your administrator privileges. +6. Follow the standard deletion process [previously outlined](#delete-organization). ## Related articles diff --git a/docs/organizations/accounts/disable-request-access-policy.md b/docs/organizations/accounts/disable-request-access-policy.md index ef630ce5a62..7e4e1060176 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: 06/05/2025 monikerRange: 'azure-devops' --- @@ -16,33 +16,37 @@ 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. +This article explains how to disable the 'Request Access' policy in Azure DevOps to prevent users from requesting access to your organization or projects. When this policy is enabled, users can request access, and administrators receive email notifications for review and approval. Disabling the policy stops these requests and notifications, helping you control access more tightly. ## 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 -1. Sign in to your organization (```https://dev.azure.com/{yourorganization}```). +1. Sign in to your organization (```https://dev.azure.com/{Your_Organization}```). 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**, find the 'Request Access' policy, and switch 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. - ![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. +**Result:** - ![Enter the URL to your organization's internal process for gaining access.](media/disable-request-access-provide-url.png) +When users try to access a project without the required permissions, the error message includes the **request access URL**. This link is shown on the error page to maintain confidentiality, regardless of whether the project exists. ## 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..8641a24fe56 100644 --- a/docs/organizations/accounts/disconnect-organization-from-azure-ad.md +++ b/docs/organizations/accounts/disconnect-organization-from-azure-ad.md @@ -1,38 +1,38 @@ --- -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' +ms.custom: sfi-image-nochange --- -# 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 +42,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-microsoft-entra-id.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..b1ee847cd52 100644 --- a/docs/organizations/accounts/faq-azure-access.yml +++ b/docs/organizations/accounts/faq-azure-access.yml @@ -1,61 +1,65 @@ ### 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 + - sfi-image-nochange + 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 +70,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 +98,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 +139,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 +211,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 +281,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 +318,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 +329,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-microsoft-entra-id.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-microsoft-entra-id.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 +381,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 +395,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 +404,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 +412,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 +453,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 +481,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..1a15aa95bc0 100644 --- a/docs/organizations/accounts/faq-user-and-permissions-management.yml +++ b/docs/organizations/accounts/faq-user-and-permissions-management.yml @@ -2,28 +2,23 @@ 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 + - sfi-image-nochange 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: 06/27/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) - + This article provides answers to frequently asked questions (FAQs) about user and permissions management in Azure DevOps. The FAQs are organized by topic to help you quickly find information about managing users, permissions, access levels, Visual Studio subscriptions, GitHub Enterprise integration, and related administrative tasks. @@ -33,45 +28,37 @@ 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). - question: | Q: How do I find the organization owner? answer: | - A: If you have at least Basic access, you can find the current owner in your organization settings. - - 1. Go to your **Organization settings**. - - ![Screenshot showing highlighted Organization settings button.](../../media/settings/open-admin-settings-vert.png) - - 2. Find the current owner. - - ![Find the current owner in organization information](../../media/find-organization-owner.png) + A: If you have at least Basic access, you can find the current owner in your organization settings. For more information, see [Look up the organization owner](../security/look-up-organization-owner.md). - question: | Q: How do I find a Project Collection Administrator? 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: | + Q: Why can't users access some features? + answer: | + A: 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: | + Q: 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 +66,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 +82,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 +100,88 @@ 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 Microsoft 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: 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 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: 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 happens when a GitHub Enterprise license is no longer detected? + answer: | + A: When a user no longer has GitHub Enterprise, they're treated like a new user. + - Your organization's default access level, whether Basic or Basic + Test Plans, gets assigned automatically. + - If your organization established Group Rules, the user receives the access specified for their Microsoft Entra group. Group rule reevaluation occurs every 24 hours, so they might initially have Stakeholder access before receiving group rule access. + + Otherwise, users who no longer have access through GitHub Enterprise maintain Stakeholder access until an administrator assigns them paid access. + + The following example shows that the license isn't detected anymore: + ![Screenshot shows GitHub Enterprise no longer listed as user's access level in Organization settings, Users page.](media/faq/github-enterprise-no-license.png) + + - question: | + Q: Are users using GitHub Enterprise Server detected as having GitHub Enterprise? + answer: | + A: No, only GitHub Enterprise cloud users are detected in Azure DevOps. Customers using GitHub Server can [sync 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 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 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 +200,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 +213,38 @@ 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 application access policies for your organization + questions: + + - question: | + Q: Can I still use PATs for authentication? + answer: | + A: You can still use personal access tokens (PATs) for authentication, but we recommend using the more secure method, Microsoft Entra tokens, whenever possible. For more information, see [Authenticate to Azure DevOps with Microsoft Entra](../../integrate/get-started/authentication/entra.md). + - question: | Q: If I deny access to one authentication method in one organization, does that affect all the organizations that I own? answer: | @@ -201,24 +257,23 @@ 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? answer: | A: To remove yourself from an organization, do the following steps: - 1. Go to [aex.dev.azure.com](https://aex.dev.azure.com). 2. Select the organization, and then choose **Leave**. - - ![Member removing their self from the organization](media/faq/member-leave-organization.png) - 3. Confirm that you want to **Leave** the organization. - - ![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: | @@ -226,18 +281,15 @@ sections: answer: | A: Users in the group **TestGroup** lose access to group resources if the users haven't been explicitly assigned to the resources or assigned via a different group rule. - > [!div class="mx-imgBorder"] - > ![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 +299,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 +320,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 +329,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 +346,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, which is 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 + PowerShell 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 + PowerShell Connect-MgGraph -Scopes 'User.Read.All' ``` b. Find the **objectId** of the user: ``` - PS Get-AzureADuser -SearchString "YourUPN" + PowerShell 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 + PowerShell 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 + PowerShell Update-MgUser -UserID -UserType Member ``` @@ -346,7 +398,7 @@ sections: - question: | Q: Why don't users appear or disappear promptly in Azure DevOps after I add or delete them in the Users hub? answer: | - A: If you experience delays finding new users or having deleted users promptly removed from Azure DevOps (for example, in drop-down lists and groups) after you add or delete users, [file a problem report on Developer Community](https://go.microsoft.com/fwlink/?LinkId=820594) so we can investigate. + A: If you experience delays finding new users or getting deleted users promptly removed from Azure DevOps (for example, in drop-down lists and groups) after you add or delete users, [file a problem report on Developer Community](https://go.microsoft.com/fwlink/?LinkId=820594) so we can investigate. @@ -359,12 +411,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 deleted file mode 100644 index fc94aa6125e..00000000000 --- a/docs/organizations/accounts/get-list-of-organizations-connected-to-azure-active-directory.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -title: Get list of organizations connected to Azure Active Directory -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). -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 -monikerRange: 'azure-devops' ---- - -# Get list of organizations backed by Azure AD - -[!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 - -## Prerequisites - -You must be a member of an Azure DevOps organization [connected to Azure AD.](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. - -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 **Download**. - - :::image type="content" source="media/shared/select-azure-ad-download.png" alt-text="Select Azure Active Directory, and then Download"::: - -## Next steps - -> [!div class="nextstepaction"] -> [Restrict organization creation with tenant policy](azure-ad-tenant-policy-restrict-org-creation.md) - -## 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) -* [Enforce Conditional Access policies](change-application-access-policies.md) -* [Manage access with Azure AD groups](./manage-azure-active-directory-groups.md) diff --git a/docs/organizations/accounts/get-list-of-organizations-connected-to-microsoft-entra-id.md b/docs/organizations/accounts/get-list-of-organizations-connected-to-microsoft-entra-id.md new file mode 100644 index 00000000000..a7b48351fec --- /dev/null +++ b/docs/organizations/accounts/get-list-of-organizations-connected-to-microsoft-entra-id.md @@ -0,0 +1,92 @@ +--- +title: Get list of organizations connected to Microsoft Entra ID +titleSuffix: Azure DevOps Services +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 +ai-usage: ai-assisted +ms.date: 05/28/2025 +monikerRange: 'azure-devops' +--- + +# 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 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 + +| Category | Requirements | +|--------------|-------------| +|Organization connection |Member of an Azure DevOps organization [connected to Microsoft Entra ID](connect-organization-to-azure-ad.md).| +|Azure DevOps CLI | Have a Microsoft Entra token. For more information, see [Issue Microsoft Entra tokens with Azure CLI](../../cli/entra-tokens.md).| + +## Get list of organizations + +#### [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}```). + +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 **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 Microsoft Entra token. You can [issue Microsoft Entra tokens with the Azure CLI](../../cli/entra-tokens.md). Use the following command to list the projects in an organization: + + ```azurerestapi + az rest --method get --uri https://dev.azure.com/{My_Organization}/_apis/projects?api-version=6.0 --headers "Authorization=Bearer {12346918273649182376491823764}" + ``` + + This process should correctly authenticate and retrieve the list of organizations connected to your Microsoft Entra ID. + +* * * + +## Next steps + +> [!div class="nextstepaction"] +> [Restrict organization creation with tenant policy](azure-ad-tenant-policy-restrict-org-creation.md) + +## Related articles + +* [Resolve orphaned organization](resolve-orphaned-organization.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 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..331e82eeea9 --- /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/git-ecosystem/git-credential-manager/). 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..51151147d6d 100644 --- a/docs/organizations/accounts/manage-azure-active-directory-groups.md +++ b/docs/organizations/accounts/manage-azure-active-directory-groups.md @@ -1,42 +1,41 @@ --- -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' +ms.custom: sfi-image-nochange --- -# 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](/entra/fundamentals/whatis). [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 +58,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 +81,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..965852b408b 100644 --- a/docs/organizations/accounts/manage-pats-with-policies-for-administrators.md +++ b/docs/organizations/accounts/manage-pats-with-policies-for-administrators.md @@ -6,95 +6,127 @@ 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: 06/12/2025 monikerRange: 'azure-devops' --- -# Use policies to manage personal access tokens for users +# Manage personal access tokens using policies (for administrators) [!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 our tenant and organization 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. -> [!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. +Each section details the default behavior of the respective policies, helping administrators effectively control and secure PAT usage within their organization. + +[!INCLUDE [use-microsoft-entra-reduce-pats](../../includes/use-microsoft-entra-reduce-pats.md)] + +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 | +|--------------|-------------| +|**Microsoft Entra tenant**| Your organization is [linked to a Microsoft Entra tenant](connect-organization-to-azure-ad.md).| +|**Permissions**|
      • Org-level policies: [Project Collection Administrator](../security/look-up-project-collection-administrators.md)
      • Tenant-level policies: [Azure DevOps Administrator](../security/look-up-azure-devops-administrator.md)
      | + -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. +### Add Microsoft Entra users or groups to policy allowlists -## Restrict creation of global PATs +> [!WARNING] +> We generally recommend using groups for your allowlists. If you list a named user, a reference to their identity resides in the United States, Europe (EU), and Southeast Asia (Singapore). -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*. +Users or groups on the allowlist for any of these policies are exempt from the restrictions and enforcements when policies are enabled. -1. Sign in to your organization (```https://dev.azure.com/{yourorganization}```). +Each policy has its own unique allowlist. To exempt a user from all policies, they must be added to each allowlist. For the tenant policies, select **Add Microsoft Entra user or group**, then select **Add**. + +## Restrict creation of global PATs (tenant policy) -2. Choose ![gear icon](../../media/icons/gear-icon.png) **Organization settings**. +Azure DevOps Administrators can restrict users from creating global PATs, which can be used in 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*. - ![Choose the gear icon, Organization settings](../../media/settings/open-admin-settings-vert.png) +1. Sign in to your organization (```https://dev.azure.com/{Your_Organization}```). -3. In the Azure Active Directory tab, find the *Restrict global personal access token creation* policy and move the toggle to *on*. +2. Select ![gear icon](../../media/icons/gear-icon.png) **Organization settings**. + + ![Screenshot showing Choose the gear icon, Organization settings.](../../media/settings/open-admin-settings-vert.png) + +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 +## Restrict creation of full-scoped PATs (tenant policy) -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*. +Azure DevOps Administrators 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**. - - ![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 *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 +## Set maximum lifespan for new PATs (tenant policy) -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*. +Azure DevOps Administrators 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**. +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 *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 + -> [!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). +## Restrict personal access token creation (organization policy) + +> [!NOTE] +> - This policy is in public preview. +> - This policy is only available for Microsoft Entra-backed organizations. -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. +Project Collection Administrators are able to control who can create and regenerate PATs in the organizations they manage. By default, this policy is set to *off*. Existing PATs continue working until the PAT's expiration date. -## Revoke leaked PATs automatically +> [!TIP] +> Combine this policy with a short duration set for the "Set maximum lifespan for new PATs" policy to drive down PAT usage in your organization. -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 policy also blocks global PAT usage in the organization. Global PAT users must be added to the allowlist to continue to use their global PAT in the organization. + +1. Sign in to your organization (```https://dev.azure.com/{Your_Organization}```). + +2. Select ![gear icon](../../media/icons/gear-icon.png) **Organization settings**. + +3. Select **Policies**, find the *Restrict personal access token (PAT) creation* policy. + + :::image type="content" source="media/disable-pat-policy/disable-pat-policy.png" alt-text="Screenshot of toggle moved to on position and subpolicies checked for Restrict personal access token creation policy."::: + +4. If your organization members regularly use packaging PATs, select the *Allow creation of PAT with packaging scope only* checkbox. Many packaging scenarios still rely on PATs and haven't fully transitioned to Microsoft Entra-based authentication. When this policy is enabled, users who aren't on the allowlist have access only to packaging scopes on their "Personal access tokens" page. + + :::image type="content" source="media/disable-pat-policy/disable-pat-packaging-only.png" alt-text="Screenshot of packaging scopes available only on the user's Create a new personal access token modal."::: + +6. If any Microsoft Entra users or groups require continued access to PATs, add them to the allowlist by selecting *Manage* and searching for the user or group in the dropdown. Once allowlist updates are complete, select the checkbox next to *Allow creation of PAT of any scope for selected Microsoft Entra users and groups*. + +7. Move the toggle to *on* in order for the restriction policy to apply. Selected subpolicies don't apply until the toggle is on. + +## Revoke leaked PATs automatically (tenant policy) + +Azure DevOps Administrators 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 @@ -102,7 +134,7 @@ The policy is disabled and any PATs that get checked into public GitHub reposito > [Change application access policies](change-application-access-policies.md) ## 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) +- [Revoke organization users' personal access tokens (for admins)](admin-revoke-user-pats.md) +- [Authenticate to Azure DevOps with Microsoft Entra](../../integrate/get-started/authentication/entra.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 deleted file mode 100644 index cf900efad0d..00000000000 --- a/docs/organizations/accounts/manage-personal-access-tokens-via-api.md +++ /dev/null @@ -1,280 +0,0 @@ ---- -title: Manage personal access tokens using API -titleSuffix: Azure DevOps -description: Learn how to use the PAT lifecycle management API to get, create, update, and revoke their personal access tokens (PATs). -ms.subservice: azure-devops-security -ms.custom: devx-track-python -ms.topic: how-to -ms.reviewer: wonga -ms.date: 12/30/2020 -monikerRange: 'azure-devops' ---- - -# Manage personal access tokens (PATs) using REST API - -[!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. - -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. - -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). - -## 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 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. - -## Authenticate with Azure Active Directory (Azure AD) tokens - -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. - -In order to acquire and refresh Azure AD access tokens, you must: - -* [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) -* [Add Azure DevOps permissions to the application](/azure/active-directory/develop/quickstart-configure-app-access-web-apis) - -> [!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) - -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. - -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. - -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 - -## 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. - -> [!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. - -## 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. - - -#### 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/). - - ![Open "Azure Active Directory" -> "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) - -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”. - - ![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) - -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) - -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) - - -### 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. - - -> [!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. - - -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. - -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. - - -> [!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: - - ```python - import os - - CLIENT_ID = "YOUR_CLIENT_ID_HERE" - # Application (client) ID of app registration - - CLIENT_SECRET = "YOUR_CLIENT_SECRET_HERE" - # Placeholder - for use ONLY during testing. - # In a production app, we recommend you use a more secure method of storing your secret, - # like Azure Key Vault. Or, use an environment variable as described in Flask's documentation: - # https://flask.palletsprojects.com/en/1.1.x/config/#configuring-from-environment-variables - # CLIENT_SECRET = os.getenv("CLIENT_SECRET") - # if not CLIENT_SECRET: - # raise ValueError("Need to define CLIENT_SECRET environment variable") - - AUTHORITY = "https://login.microsoftonline.com/YOUR_AAD_TENANT_ID_HERE" # For multi-tenant app - # AUTHORITY = "https://login.microsoftonline.com/Enter_the_Tenant_Name_Here" - - REDIRECT_PATH = "/getAToken" - # Used for forming an absolute URL to your redirect URI. - # The absolute URL must match the redirect URI you set - # in the app's registration in the Azure portal. - - ENDPOINT = 'https://graph.microsoft.com/v1.0/users' - - SCOPE = ["User.ReadBasic.All"] - - SESSION_TYPE = "filesystem" - # Specifies the token cache should be stored in server-side session - ``` - -2. Update the client ID or client secret to your application with your app registration’s client ID and client secret. When in production, make sure to secure the client secret by using an environment variable, Azure KeyVault, or by switching to a certificate. - - ```python - CLIENT_ID = "YOUR_CLIENT_ID_HERE" - # Application (client) ID of app registration - - CLIENT_SECRET = "YOUR_CLIENT_SECRET_HERE" - # Placeholder - for use ONLY during testing. - # 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: - - ```python - # Fill in the url to the user's ADO collection + the PAT lifecycle management API endpoint here - - 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: - ```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. - - ```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". - - ```python - # For single-tenant app: - AUTHORITY = "https://login.microsoftonline.com/YOUR_AAD_TENANT_ID_HERE" - - # For multi-tenant app: - 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: - - ```python - import os - - CLIENT_ID = "YOUR_CLIENT_ID_HERE" - # Application (client) ID of app registration - - # Note that the CLIENT_SECRET has been removed and moved to an environment variable or Azure KeyVault - - AUTHORITY = "https://login.microsoftonline.com/YOUR_AAD_TENANT_ID_HERE" # For multi-tenant app - # AUTHORITY = "https://login.microsoftonline.com/Enter_the_Tenant_Name_Here" - - REDIRECT_PATH = "/getAToken" - # Used for forming an absolute URL to your redirect URI. - # The absolute URL must match the redirect URI you set in the app's registration in the Azure portal. - - ENDPOINT = 'https://vssps.dev.azure.com/testCollection/_apis/Tokens/Pats?api-version=6.1-preview' - # Used to configure user's collection URL and the desired API endpoint - - SCOPE = ["499b84ac-1321-427f-aa17-267ca6975798/.default"] - # Means "All scopes for the Azure DevOps API resource" - - SESSION_TYPE = "filesystem" - # 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. - - -## 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). - - - -## FAQ - -### 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: 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: -* 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. - -To rotate your PAT, you need to: -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. - - -## Next steps -> [!div class="nextstepaction"] -> [Learn about the PAT lifecycle management API endpoints](/rest/api/azure/devops/tokens/pats) 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/disable-pat-policy/disable-pat-packaging-only.png b/docs/organizations/accounts/media/disable-pat-policy/disable-pat-packaging-only.png new file mode 100644 index 00000000000..66fa4b744ef Binary files /dev/null and b/docs/organizations/accounts/media/disable-pat-policy/disable-pat-packaging-only.png differ diff --git a/docs/organizations/accounts/media/disable-pat-policy/disable-pat-policy.png b/docs/organizations/accounts/media/disable-pat-policy/disable-pat-policy.png new file mode 100644 index 00000000000..51a3283c87b Binary files /dev/null and b/docs/organizations/accounts/media/disable-pat-policy/disable-pat-policy.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-no-license.png b/docs/organizations/accounts/media/faq/github-enterprise-no-license.png new file mode 100644 index 00000000000..94708e0c561 Binary files /dev/null and b/docs/organizations/accounts/media/faq/github-enterprise-no-license.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/my-profile-team-services-preview.png b/docs/organizations/accounts/media/my-profile-team-services-preview.png new file mode 100644 index 00000000000..16d9b382842 Binary files /dev/null and b/docs/organizations/accounts/media/my-profile-team-services-preview.png differ diff --git a/docs/organizations/accounts/media/pats/copy-token-to-clipboard.png b/docs/organizations/accounts/media/pats/copy-token-to-clipboard.png new file mode 100644 index 00000000000..f635f0ddd5e Binary files /dev/null and b/docs/organizations/accounts/media/pats/copy-token-to-clipboard.png differ diff --git a/docs/organizations/accounts/media/pats/create-new-pat.png b/docs/organizations/accounts/media/pats/create-new-pat.png new file mode 100644 index 00000000000..1a0dc71990a Binary files /dev/null and b/docs/organizations/accounts/media/pats/create-new-pat.png differ diff --git a/docs/organizations/accounts/media/pats/modify-pat.png b/docs/organizations/accounts/media/pats/modify-pat.png new file mode 100644 index 00000000000..37e80c2f3e6 Binary files /dev/null and b/docs/organizations/accounts/media/pats/modify-pat.png differ diff --git a/docs/organizations/accounts/media/pats/revoke-personal-access-tokens-preview.png b/docs/organizations/accounts/media/pats/revoke-personal-access-tokens-preview.png new file mode 100644 index 00000000000..6082767afa4 Binary files /dev/null and b/docs/organizations/accounts/media/pats/revoke-personal-access-tokens-preview.png differ diff --git a/docs/organizations/accounts/media/pats/revoke-token-confirmation-dialog-preview.png b/docs/organizations/accounts/media/pats/revoke-token-confirmation-dialog-preview.png new file mode 100644 index 00000000000..4c70f6dccca Binary files /dev/null and b/docs/organizations/accounts/media/pats/revoke-token-confirmation-dialog-preview.png differ diff --git a/docs/organizations/accounts/media/pats/select-edit-pat-current-view.png b/docs/organizations/accounts/media/pats/select-edit-pat-current-view.png new file mode 100644 index 00000000000..0e18df56256 Binary files /dev/null and b/docs/organizations/accounts/media/pats/select-edit-pat-current-view.png differ diff --git a/docs/organizations/accounts/media/pats/select-new-token.png b/docs/organizations/accounts/media/pats/select-new-token.png new file mode 100644 index 00000000000..c05f510d938 Binary files /dev/null and b/docs/organizations/accounts/media/pats/select-new-token.png differ diff --git a/docs/organizations/accounts/media/pats/select-pat-scopes-preview.png b/docs/organizations/accounts/media/pats/select-pat-scopes-preview.png new file mode 100644 index 00000000000..18d24b92826 Binary files /dev/null and b/docs/organizations/accounts/media/pats/select-pat-scopes-preview.png differ diff --git a/docs/repos/git/media/select-pat-scopes.png b/docs/organizations/accounts/media/pats/select-pat-scopes.png similarity index 100% rename from docs/repos/git/media/select-pat-scopes.png rename to docs/organizations/accounts/media/pats/select-pat-scopes.png diff --git a/docs/organizations/accounts/media/pats/select-personal-access-tokens.png b/docs/organizations/accounts/media/pats/select-personal-access-tokens.png new file mode 100644 index 00000000000..f207e98d7ce Binary files /dev/null and b/docs/organizations/accounts/media/pats/select-personal-access-tokens.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/setup-ado-cap.png b/docs/organizations/accounts/media/setup-ado-cap.png new file mode 100644 index 00000000000..d82292ae1b3 Binary files /dev/null and b/docs/organizations/accounts/media/setup-ado-cap.png 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..70fd3d226cc 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).| +|**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,14 @@ 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) +* [Assign an owner to an orphaned organization](resolve-orphaned-organization.md) diff --git a/docs/organizations/accounts/rename-organization.md b/docs/organizations/accounts/rename-organization.md index 2192f52944d..3f4acc11b32 100644 --- a/docs/organizations/accounts/rename-organization.md +++ b/docs/organizations/accounts/rename-organization.md @@ -1,32 +1,36 @@ --- 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' +ms.custom: sfi-image-nochange --- # Rename your organization in 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 +61,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..0841ba17b76 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,68 @@ 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) -### 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. - -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. - -## When you don't have an Azure DevOps Administrator +| Category | Requirements | +|--------------|-------------| +|**Permissions**|[Azure DevOps Administrator in Microsoft Entra ID](../security/look-up-azure-devops-administrator.md). 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).| -When your Azure AD tenant hasn't assigned an Azure DevOps Administrator, complete the following steps. +> [!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). -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). +### Find your Azure DevOps Administrator - > [!NOTE] - > Any changes to role membership may take up to an hour to propagate to Azure DevOps. +The Azure DevOps Administrator can [change the Azure DevOps owner](change-organization-ownership.md) to claim ownership of the target Azure DevOps organization. -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. +> [!NOTE] +> Any changes to role membership might take up to an hour to propagate to Azure DevOps. ## 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-microsoft-entra-id.md) 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..0f0ec80008d 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 @@ -46,12 +46,9 @@ - name: Resolve orphaned organization displayName: find, owner, collection, administrator, Azure Active Directory, claim ownership, href: resolve-orphaned-organization.md - - name: Restrict organization creation - displayName: settings, Azure Active Directory, role, administrator, prevent - href: azure-ad-tenant-policy-restrict-org-creation.md - - name: Use policies to manage user PATs (for admins) - displayName: restrict, creation, global, full, scope, maximum, lifespan, authentication - href: manage-pats-with-policies-for-administrators.md + - name: Set up security policies + displayName: find, owner, collection, administrator, Azure Active Directory, claim ownership, + href: change-application-access-policies.md?toc=/azure/devops/organizations/security/toc.json - name: Services status displayName: service, health, portal, geography, region, core, other, event, log, availability, RSS, REST APIs href: ../../user-guide/service-status-info.md?toc=/azure/devops/organizations/toc.json @@ -60,3 +57,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..93684240ab6 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-microsoft-entra-id.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..1a0a0cbf1de 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: 06/27/2025 monikerRange: '<= azure-devops' --- @@ -16,60 +17,268 @@ 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. Treat PATs with the same level of caution as passwords. -## About PATs +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 if you prefer not to share your primary credentials, consider using PATs as an alternative authentication method. However, we recommend using [Microsoft Entra tokens](../../integrate/get-started/authentication/entra.md) over PATs whenever possible. -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. +[!INCLUDE [use-microsoft-entra-reduce-pats](../../includes/use-microsoft-entra-reduce-pats.md)] -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. +## Prerequisites -You can create and manage your PATs through one of the following ways: +| 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 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.** See our section on [Best Practices when using PATs](#best-practices-for-using-pats).| -* 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) +## Create a PAT -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. +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**. -[!INCLUDE [personal-access-tokens](../../repos/git/includes/personal-access-tokens.md)] + :::image type="content" source="media/pats/select-personal-access-tokens.png" alt-text="Screenshot showing selection, Personal Access Tokens."::: -## Related articles +3. Select **+ New Token**. -* [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) + :::image type="content" source="media/pats/select-new-token.png" alt-text="Screenshot showing selection, New Token."::: -::: moniker range="azure-devops" +4. Name your token, select the organization where you want to use the token, and then set your token to automatically expire after a set number of days. -## FAQs + :::image type="content" source="media/pats/create-new-pat.png" alt-text="Screenshot showing entry of basic token information."::: -### Q: What happens to a PAT if a user account is disabled? +5. Select the [scopes](../../integrate/get-started/authentication/oauth.md#available-scopes) + for this token to authorize for *your specific tasks*. -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. + For example, to create a token for a [build and release agent](../../pipelines/agents/agents.md) 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**. -### Q: Is there a way to renew a PAT via REST API? + :::image type="content" source="media/pats/select-pat-scopes-preview.png" alt-text="Screenshot showing selected scopes for a PAT."::: -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). + > [!NOTE] + > Your administrator might [restrict you from creating full-scoped PATs or limit you to packaging-scope PATs only](manage-pats-with-policies-for-administrators.md). Reach out to your admin to get on the allowlist if you need access to more scopes. + > Some scopes, for example, `vso.governance`, might not be available in the UI if they aren't for widespread public use. -### Q: Can I use basic auth with all Azure DevOps REST APIs? +6. When you're done, copy the token and store it in a secure location. For your security, it doesn't display again. -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). + :::image type="content" source="media/pats/copy-token-to-clipboard.png" alt-text="Screenshot showing how to copy the token to your clipboard."::: -### Q: What happens if I accidentally check my PAT into a public repository on GitHub? +Use your PAT anywhere your user credentials are required for authentication in Azure DevOps. -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. +> [!IMPORTANT] +> - Treat a PAT with the same caution as your password and keep it confidential. **DO NOT SHARE PATS.** +> - For organizations backed by Microsoft Entra ID, you must sign in with your new PAT within 90 days or it becomes inactive. For more information, see [User sign-in frequency for Conditional Access](/azure/active-directory/conditional-access/howto-conditional-access-session-lifetime). -For more information, see [Revoke leaked PATs automatically](manage-pats-with-policies-for-administrators.md#revoke-leaked-pats-automatically). +### Notifications -### 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? +During a PAT's lifespan, users receive two notifications: one when the PAT is created and another seven days before it expires. -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). +After you create a PAT, you might receive a notification similar to the following example. This notification serves as confirmation that your PAT was successfully added to your organization. -### Q: Why did my PAT stop working? + :::image type="content" source="media/use-personal-access-tokens-to-authenticate/pat-creation.png" alt-text="Screenshot showing PAT created notification."::: -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. +An expiration notification email is sent three days before expiration. If your administrator [removed your ability to create PATs in the organization](manage-pats-with-policies-for-administrators.md), the email indicates that it's no longer possible for you to regenerate PATs. Reach out to your [Project Collection Administrator](../security/look-up-project-collection-administrators.md) to be included in an allowlist for continued PAT creation permissions in that organization. + +::: moniker range=" < azure-devops" + +For more information, see [Configure an SMTP server and customize email for alerts and feedback requests](/azure/devops/server/admin/setup-customize-alerts). ::: moniker-end +#### Unexpected notification + +If you receive an unexpected PAT notification, it might mean that an administrator or tool created a PAT for you. Here are some examples: + +- 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] +> - [Revoke the PAT](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](#q-what-happens-if-i-accidentally-check-my-pat-into-a-public-repository-on-github). + +## Use a PAT + +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. Use a PAT in your code to authenticate [REST APIs](/rest/api/azure/devops) requests and automate workflows by including the PAT in the authorization header of your request. + +> [!IMPORTANT] +> Once your app code is working, switch to [Microsoft Entra OAuth to acquire tokens on-behalf-of your app's users](../../integrate/get-started/authentication/entra-oauth.md) or a [service principal or managed identity to acquire tokens as an application](../../integrate/get-started/authentication/service-principal-managed-identity.md). It isn't recommended to keep running apps or scripts with PATs long-term. Microsoft Entra tokens can be used anywhere a PAT is used. +> Consider [acquiring a Microsoft Entra token via the Azure CLI](../../cli/entra-tokens.md) for ad-hoc requests. + +#### [Windows](#tab/Windows/) + +To provide the PAT through an HTTP header, you must first convert it to a `Base64` string. It can then be provided as an HTTP header in the following format. + +```cs + +Authorization: Basic BASE64_USERNAME_PAT_STRING +``` + +#### [Linux/macOS](#tab/Linux/) + +The following sample gets a list of builds using curl. + +```curl + +curl -u :{PAT} https://dev.azure.com/{organization}/_apis/build-release/builds +``` + +* * * + +## Modify a PAT + +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#available-scopes) of a PAT to change its permissions. + +1. From your home page, open user settings :::image type="icon" source="../../media/icons/user-settings-gear.png" border="false"::: and select **Personal access tokens**. + +2. Select the token you want to modify, and then **Edit**. + + :::image type="content" source="media/pats/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 associated with the token, and then select **Save**. + + :::image type="content" source="media/pats/modify-pat.png" alt-text="Screenshot showing modified PAT."::: + +## Revoke a PAT + +You can revoke a PAT at any time for these and other reasons: + +- **Security breach**: Revoke a PAT immediately if you suspect it is compromised, leaked, or exposed in logs or public repositories. +- **No longer needed**: Revoke a PAT when the project, service, or integration it was created for is complete or discontinued. +- **Policy compliance**: Revoke a PAT to enforce security policies, compliance requirements, or organizational token rotation schedules. +- **User changes**: Revoke a PAT when a team member leaves the organization or changes roles and no longer needs access. +- **Scope reduction**: Revoke and recreate a PAT with reduced permissions when you need to limit its access capabilities. +- **Regular maintenance**: Revoke a PAT as part of routine security hygiene and token lifecycle management. + +Do the following steps to revoke a PAT: + +1. From your home page, open user settings :::image type="icon" source="../../media/icons/user-settings-gear.png" border="false"::: and select **Personal access tokens**. + +2. Under Security, select **Personal access tokens**. Select the token for which you want to revoke access, and then select **Revoke**. + + :::image type="content" source="media/pats/revoke-personal-access-tokens-preview.png" alt-text="Screenshot showing selection to revoke a single token or all tokens."::: + +3. Select **Revoke** in the confirmation dialog. + + :::image type="content" source="media/pats/revoke-token-confirmation-dialog-preview.png" alt-text="Screenshot showing confirmation screen to revoke PAT."::: + +## PAT Lifecycle Management APIs + +The [PAT Lifecycle Management APIs](/rest/api/azure/devops/tokens) might be useful when maintaining large volumes of tokens through UI is unsustainable. Managing PAT rotation programmatically also opens the opportunity to rotate PATs regularly and shorten their default lifespans. Our [sample Python app](https://github.com/microsoft/azure-devops-auth-samples/tree/master/PersonalAccessTokenAPIAppSample) can be configured with your Microsoft Entra tenant and Azure DevOps organization. + +Some things to note about these APIs: + +* [Microsoft Entra access tokens](../../integrate/get-started/authentication/entra.md) are required to access this API as generally a stronger form of authentication is recommended when minting new tokens. +* Only users or apps using an "on-behalf-of user" flow can generate PATs. Apps using "on-behalf-of application" flows or authentication flows that don't issue Microsoft Entra access tokens aren't valid for use with this API. As such, [service principals or managed identities](../../integrate/get-started/authentication/service-principal-managed-identity.md) can't create or manage PATs. +* Previously the PAT Lifecycle Management APIs only supported the `user_impersonation` scope, but now the `vso.pats` are available and the recommended scope to use with these APIS. Downscope all apps that previously relied on `user_impersonation` to call these APIs. + +## Changes to format + +As of July 2024, we updated the format of PAT strings to improve secret detection in our [leaked PAT detection tooling](manage-pats-with-policies-for-administrators.md#revoke-leaked-pats-automatically-tenant-policy) and [partner offerings](../../repos/security/github-advanced-security-secret-scanning.md). This new PAT format includes more identifiable bits to improve the false positive detection rate in these detection tools and mitigate detected leaks faster. + +* New tokens are now **84** characters long, with 52 characters being randomized data, which improves overall entropy, making tokens more resistant to brute force attacks. +* Tokens issued by our service include a fixed `AZDO` signature at positions 76-80. + +If you're using a PAT issued before that data, regenerate your PAT. If you integrate with PATs and have PAT validation built in, update your validate code to accommodate both new and existing token lengths. + +> [!WARNING] +> Both formats remain valid for the foreseeable future. As adoption of the new format increases, we might retire older 52-character PATs. + +## Best practices for using PATs + +### Consider alternatives + +* Acquire a Microsoft Entra token via the [Azure CLI](../../cli/entra-tokens.md) for ad-hoc requests 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) to simplify credential management, with authentication set to `oauth` or Microsoft Entra tokens. + +### Creating PATs + +* Don't put personal data in the PAT name. Don't rename the PAT name to include some or all of the actual PAT token. +* Avoid creating global PATs unless necessary across all organizations. +* Use a different token per flow or user case. +* Select only the minimum scopes required for each PAT. Grant the least privilege necessary for your specific task, and create separate PATs with limited scopes for different workflows instead of using a single, broad-scoped token. If your PAT needs read-only permissions, don't provide write permissions until necessary. +* Keep PAT lifespans short (weekly is ideal, even shorter is better). + +### Managing PATs + +* **Don't share your PATs!** +* **Store your PATs in a secure key management solution**, like [Azure KeyVault](/azure/key-vault/general/overview). +* Regularly rotate or regenerate your PATs via UI or PAT Lifecycle Management APIs. +* Revoke PATs when no longer needed. +* Rotate your PATs to use the [new PAT format](#changes-to-format) for better leaked secret detection and revocation by our first-party tools. + +### For admins +* Tenant admins can set [policies to restrict](manage-pats-with-policies-for-administrators.md) global PAT creation, full scoped PAT creation, and long-lived PAT duration. +* Tenant admins can [revoke PATs for their organization users](admin-revoke-user-pats.md) if the PAT is compromised. +* Organization admins can [restrict PAT creation in an organization](manage-pats-with-policies-for-administrators.md). If PATs are still needed, limit their creation to only ones on the allowlist. + +## 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 your PATs when you're signed into any organization in the same Microsoft Entra ID by changing the *Access scope* filter, 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: 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: Can I use PATs with all Azure DevOps REST APIs? + +A: No. You can use PATs with most Azure DevOps REST APIs, but [organizations and profiles](/rest/api/azure/devops/) and the PAT Management Lifecycle APIs only support [Microsoft Entra tokens](../../integrate/get-started/authentication/entra-oauth.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 in your Azure DevOps organization's [audit log](../audit/azure-devops-auditing.md#review-audit-log). 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. + +Unless you disabled the *Automatically revoke leaked personal access tokens* policy, we immediately revoke the leaked PAT. For more information, see [Revoke leaked PATs automatically](manage-pats-with-policies-for-administrators.md#revoke-leaked-pats-automatically-tenant-policy). + +#### 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 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. 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. We recommend that you keep [IIS Basic Authentication](/iis/configuration/system.webserver/security/authentication/basicauthentication) turned **off** always. + +> [!WARNING] +> If you use Git with IIS Basic Authentication, Git breaks because it requires PATs for user authentication. You can add an extra header to Git requests to use it with IIS Basic Authentication, but we don't recommend this action. The extra header must be used for all Azure DevOps Server installations, as Windows Auth also prevents using PATs. The extra header must also include a base 64 encoding of `user:PAT`. +> ``` +> git -c http.extraheader='Authorization: Basic [base 64 encoding of "user:password"]' ls-remote http://tfsserver:8080/tfs/DefaultCollection/_git/projectName +> ``` + +#### Q: How do I create access tokens that aren't tied to a person? + +A: All PATs are associated with the user identity that created it. Applications can't create PATs. + +In Azure DevOps, you can generate access tokens that aren't linked to a specific user by using Microsoft Entra tokens issued by an [application service principal or managed identity](../../integrate/get-started/authentication/service-principal-managed-identity.md). For pipelines, use [service connections](../../pipelines/library/service-endpoints.md) to securely authenticate and authorize automated tasks without relying on user-specific credentials. + +### 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: The 'Regenerate' functionality available in the UI actually accomplishes a few actions, which can be replicated through API. + +To rotate your PAT, do the following steps: +1. See PAT metadata with a **GET** call, +2. Create a new PAT with the old PAT ID using a **POST** call, +3. Revoke the old PAT using a **DELETE** call. + +### Q: How long do expired, revoked, or inactive PATs remain visible in the Azure DevOps token list? + +A: PATs that are expired or revoked can no longer be used or regenerated. These inactive tokens stay visible for several months after expiration or revocation before being automatically removed from the display. + +### Q: I see a "Need admin approval" pop-up when I try to use a Microsoft Entra app to call the PAT Lifecycle Management APIs. +A: Your tenant's security policies require admin consent before applications can access organization resources in the organization. Reach out to your tenant administrator. + +### Q: Can I use a service principal to create or manage PATs? +A: No, PATs belong to a user identity. Microsoft Entra [service principals or managed identities](../../integrate/get-started/authentication/service-principal-managed-identity.md) can generate short-lived Microsoft Entra tokens that you can use in most places where a PAT is accepted. Learn more about [our efforts to reduce PAT usage across Azure DevOps](https://devblogs.microsoft.com/devops/reducing-pat-usage-across-azure-devops/) and explore replacing PATs with Microsoft Entra tokens. + +## 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) +* [Authenticate with Microsoft Entra tokens](../../integrate/get-started/authentication/entra.md) diff --git a/docs/organizations/audit/auditing-events.md b/docs/organizations/audit/auditing-events.md index 52cca7d7ce2..38675e5bfe7 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 @@ -16,40 +16,38 @@ ms.date: 08/03/2022 [!INCLUDE [version-eq-azure-devops](../../includes/version-eq-azure-devops.md)] > [!NOTE] -> Auditing is still in public preview. +> - Auditing is still in public preview. +> - We continually add new actions to this list. To view an event that isn't currently included in the following tables, share your feedback in the [Developer Community](https://developercommunity.visualstudio.com/search?space=21). The following tables describe the type of events (or actions) that are available for auditing through the Azure DevOps Auditing feature. [!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). - -> [!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). +* 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). ## Areas | 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 +63,311 @@ 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.HostedParallelismPaid` | Organization's hosted pipeline capacity set to paid tier only.| +| `Pipelines.HostedParallelismPrivate` | Organization's hosted pipeline capacity set to free tier limit for private projects. | +| `Pipelines.HostedParallelismPublic` | Organization's hosted pipeline capacity set to free tier limit for public projects. | +| `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. | +| `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.ProjectSettings` | Pipelines setting "{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.VariablesSetAtRuntime` | A run of pipeline "{PipelineName}" in project {ResolveProjectId:ProjectId}, has defined variable(s) that are not marked as "Settable at queue time".| +| `CheckConfiguration.ApprovalCheckOrderChanged`| >A check with id {CheckId} for {ResourceType} "{ResourceName}" in project "{ResolveProjectId:ProjectId}" has been changed from {OriginalApprovalType} to {FinalApprovalType} | +| `CheckConfiguration.Created`| A check of type {Type} has been added to {ResourceType} "{ResourceName}" in project "{ResolveProjectId:ProjectId}" | +| `CheckConfiguration.Deleted`| A check of type {Type} has been removed from {ResourceType} "{ResourceName}" in project "{ResolveProjectId:ProjectId}" | +| `CheckConfiguration.Disabled` | A check of type {Type} has been disabled for {ResourceType} "{ResourceName}" in project "{ResolveProjectId:ProjectId}" | +| `CheckConfiguration.Enabled`| A check of type {Type} has been enabled for {ResourceType} "{ResourceName}" in project "{ResolveProjectId:ProjectId}" | +| `CheckConfiguration.Updated`| A check of type {Type} has been updated for {ResourceType} "{ResourceName}" in project "{ResolveProjectId:ProjectId}" | + + +### 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..2d8dc6f84d1 100644 --- a/docs/organizations/audit/auditing-streaming.md +++ b/docs/organizations/audit/auditing-streaming.md @@ -8,7 +8,8 @@ ms.author: chcomley author: chcomley ms.topic: quickstart monikerRange: '= azure-devops' -ms.date: 06/15/2023 +ms.date: 11/11/2024 +ms.custom: sfi-image-nochange --- # Create audit streaming @@ -35,26 +36,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 +73,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 +84,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 +141,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 +150,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 +166,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..5002007e50f 100644 --- a/docs/organizations/audit/azure-devops-auditing.md +++ b/docs/organizations/audit/azure-devops-auditing.md @@ -1,14 +1,16 @@ --- -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 +ms.custom: sfi-image-nochange --- # Access, export, and filter audit logs @@ -18,40 +20,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 +50,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 +88,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 +113,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 +136,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..9d6e1758bfa 100644 --- a/docs/organizations/billing/billing-faq.yml +++ b/docs/organizations/billing/billing-faq.yml @@ -2,14 +2,17 @@ metadata: title: Billing FAQs titleSuffix: Azure DevOps - ms.custom: seodec18, freshness-fy22q1, engagement-fy23 + ms.custom: + - freshness-fy22q1 + - engagement-fy23 + - sfi-image-nochange 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 +28,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 +39,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 +66,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 +130,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 +144,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 +162,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 +199,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 +222,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 +267,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 +290,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 +312,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 +356,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 +368,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 +389,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 +423,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..368f1119c4e 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,65 +1,145 @@ --- -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 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: 06/24/2025 monikerRange: 'azure-devops' +ms.custom: + - freshness-fy22q1 + - engagement-fy23 + - sfi-image-nochange --- -# 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. +This article guides you through managing billing in Azure DevOps, which is essential for controlling costs associated with users, CI/CD concurrency, and extensions. You'll learn how 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. -## Next steps + + +## 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). If billing is set up for an organization that you don't recognize, you can [look up the owner for organizations connected to your Microsoft Entra ID](../accounts/get-list-of-organizations-connected-to-microsoft-entra-id.md). + +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 step > [!div class="nextstepaction"] > [Pay for users](buy-basic-access-add-users.md) -## Related articles +## Related content -* [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-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..7b722cf36bd 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: 04/23/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,12 @@ 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). + > [!IMPORTANT] + > During the trial, users assigned **Basic + Test Plans** have full access. After trial expiration, you start getting charged for users assigned **Basic + Test Plans**, or if you haven't [set up billing](set-up-billing-for-your-organization-vs.md), those users receive **Stakeholder** access. ## Next steps @@ -54,7 +53,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..22f4dcc1e09 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 @@ -44,20 +44,20 @@ landingContent: url: ./accounts/organization-management.md - text: Plan your organizational structure 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 - url: ./accounts/access-with-azure-ad.md - linkListType: quickstart links: - text: Create an organization url: ./accounts/create-organization.md?toc=/azure/devops/organizations/toc.json + - linkListType: concept + links: + - text: Manage access with Microsoft Entra ID + url: ./accounts/access-with-azure-ad.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/toc.json - - text: Connect your organization to Azure Active Directory - url: ./accounts/connect-organization-to-azure-ad.md?toc=/azure/devops/organizations/toc.json + - text: Connect your organization to Microsoft Entra ID + url: ./accounts/connect-organization-to-azure-ad.md?toc=/azure/devops/organizations/security/toc.json - title: Add & manage projects linkLists: - linkListType: concept @@ -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..9b1167c43b4 100644 --- a/docs/organizations/notifications/about-notifications.md +++ b/docs/organizations/notifications/about-notifications.md @@ -1,38 +1,38 @@ --- -title: About notifications -description: Learn how to configure and manage notifications in Azure DevOps organizations to stay informed and improve collaboration within development teams. +title: About Notifications +description: Configure and manage notifications in Azure DevOps organizations, stay informed, and improve collaboration within development teams. ms.subservice: azure-devops-notifications toc: show ms.custom: quarterly-update, engagement-fy23 ms.author: chcomley author: chcomley -ms.topic: conceptual -ms.date: 02/13/2023 -monikerRange: '<= azure-devops' +ms.topic: concept-article +ms.date: 05/08/2025 +#customer intent: As a developer, I want to configure and manage notifications in Azure DevOps organizations so I can stay informed and improve collaboration within my development teams. --- # About notifications [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -Notifications in Azure DevOps keep you and your team informed about project activity, including changes to work items, code reviews, pull requests, source control files, and builds. When an event occurs in Azure DevOps, its content is compared with every subscription of that event type, and a notification is generated for every subscription/event match that meets the filter conditions. Notifications are delivered through email or service hook, based on the delivery properties defined in the subscription. +Notifications in Azure DevOps keep you and your team informed about project activity, including changes to work items, code reviews, pull requests, source control files, and builds. When an event occurs in Azure DevOps, the event content is compared with every subscription of that event type. A notification is generated for every subscription/event match that meets the filter conditions. Notifications are delivered through email or service hook, based on the delivery properties defined in the subscription. For more information, see the list of [supported event types](oob-supported-event-types.md) and [learn more about email delivery options](concepts-email-recipients.md). ## Notification types -There are four types of notifications that you can manage in Azure DevOps. See the following table of the notification types and required permission or role to manage. +There are four types of notifications that you can manage in Azure DevOps. The following table lists the types and the permissions or role required to manage each notification. -| Notification type | Role required to manage | -|---------------------------------------------|-------------------------------------------------------| -|[Personal notifications](#personal-notifications) | User | -|[Team notifications](#team-and-project-level-notifications) | Team Administrator or member of the Project Administrators group or Project Collection Administrators group | -|[Project notifications](#team-and-project-level-notifications) | Member of the Project Administrators group or Project Collection Administrators group | -|[Global notifications](#global-notifications)| Member of the Project Collection Administrators group | +|Notification type |Role required to manage | +|------------------|------------------------| +| [Personal notifications](#personal-notifications) | User | +| [Team notifications](#team-and-project-level-notifications) | Team Administrator, or member of the Project Administrators group or Project Collection Administrators group | +| [Project notifications](#team-and-project-level-notifications) | Member of the Project Administrators group or Project Collection Administrators group | +| [Global notifications](#global-notifications) | Member of the Project Collection Administrators group | ### Personal notifications -You can manage your personal notifications in the following manner. +There are several ways you can manage your personal notifications: - View your notifications - Set alerts only for yourself @@ -44,25 +44,21 @@ For more information, see [Manage your personal notifications](manage-your-perso ### Team and project-level notifications -You can create a subscription for the following categories and select from the following templates. +For team and project-level notifications, you can create a subscription for the following categories and templates: -|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
      | - -:::moniker range=">= azure-devops-2020" +|Category |Templates | +|---------|----------| +| **Build** | _Build completes_, _Build fails_,
      _Status changes for legacy XAML build controller or agent_,
      _Quality changes for legacy XAML build_ | +| **Code (Git)** | _Commit pushed_, _Comment added to pull request_,
      _Pull request created or updated_,
      _Pull request in review by my team updated_ | +| **Code (TFVC)** | _Code checked in_, _Code checked in with policy override_,
      _Changes to code review_, _File in specific path checked in_,
      _File with specific extension checked in_ | +| **Pipelines** | _Run stage waiting for approval_,
      _Run stage waiting for manual validation_ | +| **Work** | _Work item created_, _Work item changed_, _Work item deleted_,
      _Work item restored_, _Work item moved from this team project_ | +| **Artifacts** | _Package changed_ | +| **Extension management** | _Extension modified_ | +| **Release** | _Deployment approval pending_, _Deployment completes_,
      _Release creation request fails_,
      _Manual intervention for deployment pending_ | > [!NOTE] -> You can also create a custom notification subscription for pull requests that are created or updated in a **draft state**. For more information, see [Custom notification subscription for draft pull requests](/azure/devops/release-notes/2020/repos/sprint-165-update#custom-notification-subscription-for-draft-pull-requests). - -:::moniker-end +> You can also create a custom notification subscription for pull requests created or updated in a **draft state**. For more information, see [Custom notification subscription for draft pull requests](/azure/devops/release-notes/2020/repos/sprint-165-update#custom-notification-subscription-for-draft-pull-requests). For more information, see [Manage team, group, and global notifications](manage-team-group-global-organization-notifications.md). @@ -72,60 +68,57 @@ Global notifications apply to all **projects** defined for an organization or co ## Subscriptions -A notification **subscription** is associated with a [supported event type](oob-supported-event-types.md). The subscription includes a set of filters used to match events. For example, a subscription for a _work item created_ event might include a filter that matches only the work item type, _Bug_. Or a subscription for a _pull request created_ event might include a filter for a specific _repository and branch_. +A notification **subscription** is associated with a [supported event type](oob-supported-event-types.md). The subscription includes a set of filters that are used to match events. For example, a subscription for a _work item created_ event might include a filter that matches only the work item type, _Bug_. Or, a subscription for a _pull request created_ event might include a filter for a specific _repository and branch_. ### Default email subscriptions -Many useful email subscriptions are predefined and enabled by default in the system. They're known as **default subscriptions**. Default subscriptions provide out-of-box support for the most common notification scenarios. See the list of [available default subscriptions](oob-built-in-notifications.md). +Many useful email subscriptions are predefined and automatically enabled in the system. These resources and are referred to as **default subscriptions**. Default subscriptions provide out-of-box (OOB) support for the most common notification scenarios. For more information, see the list of [available default subscriptions](oob-built-in-notifications.md). -An organization or team administrator can choose which of the default subscriptions to make available to their users. Learn how to [manage team and organization notifications](manage-team-group-global-organization-notifications.md). +An organization or team administrator can choose which of the default subscriptions to make available to their users. For more information, see [Manage notifications for a team, project, or organization](manage-team-group-global-organization-notifications.md). -Individual users can choose to opt out of any default subscription while other team members remain subscribed. Learn how to [manage personal notification subscriptions](manage-your-personal-notifications.md). +Individual users can choose to opt out of any default subscription while other team members remain subscribed. For more information, see [Manage your personal notifications](manage-your-personal-notifications.md). -The **Default subscriptions** tab lists all default global subscriptions available. The ![globe](media/oob-notification.png) on a notification subscription indicates the subscription is a default subscription. View all [default notification subscriptions](./oob-built-in-notifications.md). +The **Default subscriptions** section in Azure DevOps lists all default global subscriptions available. The globe icon :::image type="icon" source="media/oob-notification.png"::: indicates a default or OOB subscription. For more information, see [Default and supported notifications](./oob-built-in-notifications.md). -Members of the **Project Collection Administrators** group have permission to enable/disable any default subscription in this view. Any member of the **Project Collection Valid Users** group has permission to view the details of the default subscription. The view and enable options are available in the context menu (`...`) associated with each individual subscription. +Members of the **Project Collection Administrators** group have permission to enable/disable any default subscription in this view. Any member of the **Project Collection Valid Users** group has permission to view the details of the default subscription. The view and enable options are available in the **More options** menu (**...**) associated with each individual subscription. - :::image type="content" source="media/view-organization-notification-default-subscriptions.png" alt-text="Screenshot of the organization-level notifications page: Default subscriptions tab."::: +:::image type="content" source="media/view-organization-notification-default-subscriptions.png" alt-text="Screenshot of the organization-level notifications page showing the Default subscriptions section."::: ### Custom email subscriptions -Organization or team administrators can create **Custom email subscriptions** that apply to all members of the organization or team. Learn how to [manage team and organization notifications](./manage-team-group-global-organization-notifications.md). To learn more about querying with group clauses, see [Create managed queries](../../boards/queries/using-queries.md#group-clauses). +Organization or team administrators can create **Custom email subscriptions** that apply to all members of the organization or team. For more information, see [Manage notifications for a team, project, or organization](./manage-team-group-global-organization-notifications.md). To learn more about querying with group clauses, see [Define a work item query](../../boards/queries/using-queries.md#group-clauses). -Individuals can also create custom subscriptions, which apply only to them. Learn how to [manage personal subscriptions](manage-your-personal-notifications.md). +Users can also create custom subscriptions, which apply only to them. For more information, see [Manage your personal notifications](manage-your-personal-notifications.md). ### Custom service hook subscriptions -Use **service hooks subscriptions** to integrate with third-party services. When an Azure DevOps event matches a service hook subscription, the third-party service receives a notification. For example, when an Azure DevOps build completes, a notification goes to a Slack channel with links back to the build artifact in Azure DevOps. See [Integrating with third party services](integrate-third-party-services.md). - +Use **service hooks subscriptions** to integrate with third-party services. When an Azure DevOps event matches a service hook subscription, the third-party service receives a notification. For example, when an Azure DevOps build completes, a notification goes to a Slack channel with links back to the build artifact in Azure DevOps. For more information, see [Integrate with third party services](integrate-third-party-services.md). #### Subscribers The **Subscribers** section begins with an empty identity search box. Enter any group, team, or individual to view the list of subscriptions associated with the specified identity. -You can find all notification subscriptions for the chosen identity in this view. Management options are available from the context menu (`...`) associated with each subscription. The ![globe](media/oob-notification.png) on subscription row indicates a default subscription. +You can find all notification subscriptions for the specified identity in this view. Management options are available from the **More options** menu (**...**) associated with each subscription. The globe icon :::image type="icon" source="media/oob-notification.png"::: indicates a default or OOB subscription. - :::image type="content" source="media/view-organization-notification-subscribers.png" alt-text="Screenshot of organization-level notifications page: Subscribers list."::: +:::image type="content" source="media/view-organization-notification-subscribers.png" alt-text="Screenshot of organization-level notifications page showing the Subscribers list section."::: #### Statistics -The **Statistics** section shows the most active notification subscriptions and the top event initiators (group, team, or individual). The statistics are only for the current day and reset at 00:00 UTC. A benefit of these statistics is identifying unintended high-volume subscriptions or event initiators. +The **Statistics** section shows the most active notification subscriptions and the top event initiators (group, team, or individual). The statistics are for the current day only and the values reset at 00:00 UTC. One benefit of viewing the statistics is the ability to identify unintended high-volume subscriptions or event initiators. - :::image type="content" source="media/view-organization-notification-stats.png" alt-text="Screenshot of organization-level notifications page, Statistics section."::: +:::image type="content" source="media/view-organization-notification-stats.png" alt-text="Screenshot of organization-level notifications page showing the Statistics section."::: #### Settings -Manage global-level **Settings**, such as delivery preferences. - -The **Settings** section allows organization-level management by any member of the **Project Collection Administrators** group. All teams and groups inherit the _Default delivery option_ setting. This setting, _Default delivery option_, isn't explicitly set at the team or group level. +Manage global-level **Settings**, such as delivery preferences. The **Settings** section allows organization-level management by any member of the **Project Collection Administrators** group. All teams and groups inherit the _Default delivery option_ setting, which isn't explicitly set at the team or group level. - :::image type="content" source="media/view-organization-notification-settings.png" alt-text="Screenshot of organization-level notifications page: Settings."::: +:::image type="content" source="media/view-organization-notification-settings.png" alt-text="Screenshot of organization-level notifications page showing the Settings section."::: For more information, see [Manage team, group, and global notifications](manage-team-group-global-organization-notifications.md). ## Permissions for notifications -There are no UI permissions associated with managing email notifications or alerts. Instead, they can be managed using the [TFSSecurity command line tool](/azure/devops/server/command-line/tfssecurity-cmd#collection-level-permissions). +There are no UI permissions associated with managing email notifications or alerts. Instead, you can manage access by using the [TFSSecurity command line tool](/azure/devops/server/command-line/tfssecurity-cmd#collection-level-permissions). - 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 **Edit collection-level information** permission, can set alerts for others or for a team, within that collection. @@ -133,39 +126,17 @@ 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. - -> [!NOTE] -> Your preferred email address applies across all of your organizations and cannot be changed on a per-organization basis. - -::: moniker range=" < azure-devops" - +By default, the preferred contact email address for your organization profile receives notifications. This email address is usually the same address you use to sign into Azure DevOps. You can manage this email address from your organization preferences profile page. -## Integrating with other services +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). -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. - -- [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) -- [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) - -You can also use a third-party service like Zapier to send notifications to hundreds of other services. Learn more about [Zapier and Azure DevOps Services integration](../../service-hooks/overview.md). - -::: moniker-end - -::: moniker range="< azure-devops" - -## On-premises SMTP server - -[!INCLUDE [note-smtp-server](includes/note-smtp-server.md)] - -::: moniker-end +> [!NOTE] +> Your preferred contact email address applies to all your organizations and can't be changed on a per-organization basis. -## Related articles +## Related content - [Default and supported notifications](oob-built-in-notifications.md) - [Query with group clauses](../../boards/queries/using-queries.md#group-clauses) - [FAQs](faq-notifications.yml) - [Default permissions and access set for collaboration tools](../../project/wiki/wiki-readme-permissions.md?toc=/azure/devops/organizations/notifications/toc.json&bc=/azure/devops/organizations/notifications/breadcrumb/toc.json) -- [Azure DevOps data protection overview](../../organizations/security/data-protection.md?toc=/azure/devops/organizations/notifications/toc.json&bc=/azure/devops/organizations/notifications/breadcrumb/toc.json) +- [Azure DevOps data protection overview](../../organizations/security/data-protection.md?toc=/azure/devops/organizations/notifications/toc.json&bc=/azure/devops/organizations/notifications/breadcrumb/toc.json) \ No newline at end of file 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=" [!div class="mx-imgBorder"] ->![Screenshot of preferred email address.](media/email-personal-preferred.png) +:::image type="content" source="media/email-personal-preferred.png" alt-text="Screenshot that shows how to configure the preferred email address for a personal subscription."::: ### Custom email address on a personal subscription -> [!div class="mx-imgBorder"] ->![Screenshot of custom email address.](media/email-personal-other.png) +:::image type="content" source="media/email-personal-other.png" alt-text="Screenshot that shows how to configure a custom email address for a personal subscription."::: ## Delivery settings for teams and groups -Delivery settings control the default delivery behavior when the team or group is the recipient of a notification. The subscription's configured with a delivery option that looks at the recipients' delivery settings. +Delivery settings control the default delivery behavior when the team or group is the recipient of a notification. Each subscription is configured with a delivery option that looks at the recipients' delivery settings. -You can manage subscriptions and delivery settings at the team-level or organization-level. +You can manage subscriptions and delivery settings at the team level or organization level. ### Organization-level settings -::: moniker range=">= azure-devops-2019" - -1. In **Organization settings**, select **Global notifications** > **Subscribers** > your **Team** > **Delivery settings**. - - ![Screenshot showing Team Delivery settings.](media/team-delivery-settings-new-ui.png) - -::: moniker-end - -::: moniker range="tfs-2018" +In **Organization settings**, select **Global notifications** > **Subscribers** > \ > **Delivery settings**. -1. In Organization settings, select your **Team** > **Subscribers** > **Delivery settings**. +:::image type="content" source="media/team-delivery-settings-new-ui.png" border="false" alt-text="Screenshot that shows how to configure team delivery settings for an organization." lightbox="media/team-delivery-settings-new-ui.png"::: - ![Screenshot showing organization-level settings.](media/email-team-subscribers-view.png) +Select from the following settings: -::: moniker-end +- **Deliver to email address**: Notifications are delivered to a specific email address. +- **Deliver to individual members**: Notifications are delivered to each member of the group or team. This setting is usually the default option. For more information, see [Team expansion](#team-and-group-expansion-for-email-recipients). +- **Do not deliver**: Notifications aren't delivered by default. -2. Select from the following settings: +:::image type="content" source="media/email-team-delivery-settings.png" border="false" alt-text="Screenshot of the team Delivery settings dialog showing the 'Deliver to individual members' options selected."::: -* **Deliver to email address:** notifications get delivered to a specific email address. -* **Deliver to individual members:** notifications get delivered to each member of the group or team. This setting is usually the default option. For more information about the default option, see [Team expansion](#team-and-group-expansion-for-email-recipients). -* **Do not deliver:** notifications aren't delivered by default. - - ![Screenshot showing Team Delivery settings dialog.](media/email-team-delivery-settings.png) - -If you don't explicitly choose delivery settings for a team or group, it gets determined from the [organization-level delivery setting](manage-team-group-global-organization-notifications.md). The default is either _Deliver to individual members_ or _Do not deliver_. +If you don't explicitly choose delivery settings for a team or group, the settings are determined from the [delivery options set at the organization level](manage-team-group-global-organization-notifications.md). The default value is either **Deliver to individual members** or **Do not deliver**. > [!TIP] -> The delivery settings dialog doesn't indicate whether the current selection was explicitly set or if it was inherited. +> The delivery settings dialog doesn't indicate whether the current selection is explicitly set or inherited. ## Custom team and group subscription recipients -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. +The recipients for a custom team or group subscription are determined by the subscription. For certain delivery options, the default delivery setting for the team is used to determine the set of recipients. -::: moniker range=">= azure-devops-2019" - -![email-team-delivery-options](media/email-team-delivery-options-new.png) +:::image type="content" source="media/email-team-delivery-options-new.png" border="false" alt-text="Screenshot that shows how to configure the email delivery options for a custom team or group subscription."::: The following delivery options are available for a group or team subscription: -* **Members of team by role:** recipients are members of the team or group that have one of the selected roles (for example, work item assignee) -* **Team preference:** recipients are determined by the delivery setting of the team or group (_Do not deliver_, _preferred email address_, or _members of team_) -* **Custom email address:** recipient is the specified email address -* **Members of team:** recipients are all members of the team or group, except members who have opted out of the subscription. -* **SOAP:** similar to API Management, recipients are specified by adding their email addresses (subscribing) to the SOAP service. +- **Members of team by role**: Recipients are members of the team or group that have one of the selected roles (for example, Work Item Assignee). +- **Team preference**: Recipients are determined by the delivery setting of the team or group (**Do not deliver**, **Preferred email address**, or **Members of team**). +- **Custom email address**: Recipient is the specified email address. +- **Members of team**: Recipients are all members of the team or group, except members who are opted out of the subscription. +- **SOAP**: Similar to API Management, recipients are specified by adding their email addresses (subscribing) to the SOAP service. > [!NOTE] > The default delivery setting of each member is honored, including groups that are members of the team or group. -::: 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). +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). -![Screenshot showing email team delivery option role.](media/email-team-delivery-option-role.png) +:::image type="content" source="media/email-team-delivery-option-role.png" border="false" alt-text="Screenshot that shows the email team delivery option role."::: -The option _Skip initiator_, which appears for most event types, controls whether the user or group that started the event should be explicitly excluded from the set of recipients. In general, this option should be "on" since most users don't want to receive a notification about something they did. +The **Skip initiator** option, which appears for most event types, controls whether the user or group that started the event should be explicitly excluded from the set of recipients. In general, this option should be enabled (On) because most users don't want to receive a notification about their own actions. ### Team preference The delivery option is taken from the team's delivery setting and can be one of the following options: -* **Deliver to email address:** The email is delivered to the team's preferred email address. -* **Deliver to individual members:** See the following option, [Members of team_](#members-of-team). -* **Do not deliver:** No email is delivered. +- **Deliver to email address**: The email is delivered to the team's preferred email address. +- **Deliver to individual members**: The process is described in the following section, [Members of team_](#members-of-team). +- **Do not deliver**: No email is delivered. -![Screenshot showing email team delivery option preference.](media/email-team-delivery-option-preference.png) +:::image type="content" source="media/email-team-delivery-option-preference.png" border="false" alt-text="Screenshot that shows the email team delivery option preference."::: -The team's delivery setting value is displayed after the _Address_ label and can't be changed. +The team's delivery setting value is displayed after the **Address** label and can't be changed. ### Custom email address -The notification gets sent to multiple custom email addresses, which are separated by semicolons. +The notifications are sent to multiple custom email addresses, which are separated by semicolons. + +:::image type="content" source="media/email-team-delivery-option-custom.png" border="false" alt-text="Screenshot that shows the custom email team delivery options."::: -![Screenshot showing custom email team delivery options.](media/email-team-delivery-option-custom.png) ### Members of team -The team or group membership is expanded to determine the email recipients. In the simple case, a team or group expands to a list of individuals and each is included on the **To:** line of the resulting email. However, the results of this expansion can be complicated and are explained in more detail in the [team and group expansion](#team-and-group-expansion-for-email-recipients) section. +The team or group membership is expanded to determine the email recipients. In the simple case, a team or group expands to a list of individuals and each user is included on the **To**: line of the resulting email. However, the results of the expansion can be complicated and are explained in more detail in the [team and group expansion](#team-and-group-expansion-for-email-recipients) section. -![Screenshot showing the name of a team for email delivery.](media/email-team-delivery-option-members.png) +:::image type="content" source="media/email-team-delivery-option-members.png" border="false" alt-text="Screenshot showing the name of a team for email delivery."::: ## Default subscription recipients -The delivery option for a default subscription is usually one or more roles. You can't change these values. The roles and the _Skip initiator_ option vary depending on the event type. For more information and a list of roles available for each event type, see [Supported event types](oob-supported-event-types.md). +The delivery option for a default subscription is usually one or more roles. You can't change these values. The roles and the **Skip initiator** option vary depending on the event type. For more information and a list of roles available for each event type, see [Supported event types](oob-supported-event-types.md). -![Screenshot showing recipients for default subscriptions.](media/email-delivery-default-subscription.png) +:::image type="content" source="media/email-delivery-default-subscription.png" border="false" alt-text="Screenshot showing recipients for default subscriptions."::: > [!NOTE] > The _Skip initiator_ option isn't available for all event types. + ## Team and group expansion for email recipients -When a team or group receives a notification, and either the subscription or delivery preference is for all members, the team must be "expanded" to determine the actual set of email recipients. This is a potentially recursive process that starts by looking at the team's direct members. +When a team or group receives a notification, and either the subscription or delivery preference is for all members, the team must be "expanded" to determine the actual set of email recipients. This process is potentially recursive, and starts by looking at the team's direct members. -Only members who have **not** opted out of the subscription get considered for the final recipient list. Any member who's an individual user gets added to the recipient list. +Only members who are **not** opted out of the subscription are considered for the final recipient list. Any member who's an individual user is added to the recipient list. -Only Azure DevOps Services groups remain. For each group, the group's delivery preferences get examined: +Only Azure DevOps Services groups remain. For each group, the group's delivery preferences are examined: -* "Do not deliver": no further evaluation is done on this group and the next member group is evaluated -* "Deliver to email address": the email address is added to the final recipient list -* "Deliver to individual members": the group is expanded (like its parent group) and the same rules for evaluating its members are followed +- **Do not deliver**: No further evaluation is done on this group and the next member group is evaluated. +- **Deliver to email address**: The email address is added to the final recipient list. +- **Deliver to individual members**: The group is expanded (like its parent group) and the same rules for evaluating its members are followed. ### Scenarios -Let's look at a few scenarios. We use the following symbols to denote the types of members: +This section explores several example scenarios. The following examples use symbols to denote the types of team members: + +- `I`: Individual user +- `T`: Nested team or group +- `E`: Email-enabled Microsoft Entra group + +#### Team member enables "Do not deliver" setting + +Example team members: + +- The primary team has three members: users `I1` and `I2`, and nested team `T1`. +- Team `T1` has the **Do not deliver** setting enabled. + +Only users `I1` and `I2` receive the notification messages at their preferred contact email address. Members of the nested team `T1` aren't notified. + +#### Team member enables "Deliver to individual members" setting + +Example team members: + +- The primary team has three members: users `I1` and `I2`, and nested team `T1`. +- Team `T1` has two member users, `I2` and `I3`. +- User `I2` is a member of both the primary team and team `T1`. +- Team `T1` has the **Deliver to individual members** setting enabled. + +Team `T1` is expanded to identify its members. `I1`, `I2`, and `I3` all receive the notification messages at their preferred contact email address. + +#### Team contains nested group + +Example team members: + +- The primary team has three members: users `I1` and `I2`, and nested team `T1`. +- Team `T1` has three members: users `I2` and `I3`, and nested team `T2`. +- Team `T2` has two member users, `I4` and `I5`. +- User `I2` is a member of both the primary team and team `T1`. +- Team `T1` has the **Do not deliver** setting enabled. +- Team `T2` has the **Deliver to individual members** setting enabled. + +Because team `T1` has the **Do not deliver** setting enabled, the team **isn't** expanded to identify its members. Although team `T2` has the **Deliver to individual members** setting enabled, team `T2` is nested within team `T1`. The **Do not deliver** delivery preferences for `T1` takes precedence over settings made by its members. Only users `I1` and `I2` receive the notification messages at their preferred contact email address. + +#### Team member is Microsoft Entra group + +In this example, the primary team has three members: users `I1` and `I2`, and nested Microsoft Entra group `E1`. -* `I`: individual user -* `T`: nested team or group -* `A`: mail-enabled Azure Active Directory (Azure AD) group. +Only users `I1` and `I2` receive the notification messages at their preferred contact email address unless `E1` is configured as an email-enabled security group. If `E1` is email-enabled, all members of `E1` will also receive the notifications. -| 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. | +Azure DevOps notifications don't expand to Microsoft Entra groups for delivering notifications to individual users. However, if you're using an Active Directory (AD) group that is categorized as an Email-enabled Security group in the Azure Portal, notifications can be delivered to all members within that group. This means that if your Entra Group is configured as an email-enabled security group, all members receive notifications as intended. -## Related articles +## Related content - [Manage notifications for a team, group, global organization](manage-team-group-global-organization-notifications.md) - [Default and supported notifications](oob-built-in-notifications.md) -- [Permissions, security groups, and service accounts reference](../../organizations/security/permissions.md) +- [Permissions, security groups, and service accounts reference](../../organizations/security/permissions.md) \ No newline at end of file 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/note-smtp-server.md b/docs/organizations/notifications/includes/note-smtp-server.md index f6f88b8442b..968311d8d71 100644 --- a/docs/organizations/notifications/includes/note-smtp-server.md +++ b/docs/organizations/notifications/includes/note-smtp-server.md @@ -4,13 +4,12 @@ ms.manager: mijacobs ms.author: chcomley author: chcomley ms.topic: include -ms.date: 01/23/2020 +ms.date: 05/12/2025 --- ::: moniker range="< azure-devops" > [!NOTE] -> For on-premises Azure DevOps Server, [configure an SMTP server](/azure/devops/server/admin/setup-customize-alerts) for team members to see the **Notifications** option from their [organization or user profile menu](../navigating-the-ui.md) and to receive notifications. - -::: moniker-end +> For on-premises Azure DevOps Server, [configure an SMTP server](/azure/devops/server/admin/setup-customize-alerts) so team members can see the **Notifications** option from their [organization or user profile menu](../navigating-the-ui.md) and receive notifications. +::: moniker-end \ No newline at end of file diff --git a/docs/organizations/notifications/includes/note-ui-changes.md b/docs/organizations/notifications/includes/note-ui-changes.md index 547658475a4..4a8a346adb6 100644 --- a/docs/organizations/notifications/includes/note-ui-changes.md +++ b/docs/organizations/notifications/includes/note-ui-changes.md @@ -4,8 +4,8 @@ ms.manager: mijacobs ms.author: chcomley author: chcomley ms.topic: include -ms.date: 01/06/2022 +ms.date: 05/12/2025 --- > [!NOTE] -> Many of the concepts addressed in this article are applicable to earlier versions of Azure DevOps, although the user interface may have changed. +> Many concepts addressed in this article apply to earlier versions of Azure DevOps, although there are changes to the user interface. \ No newline at end of file diff --git a/docs/organizations/notifications/includes/opt-out-notification.md b/docs/organizations/notifications/includes/opt-out-notification.md index 722e831401a..74c8f1373a2 100644 --- a/docs/organizations/notifications/includes/opt-out-notification.md +++ b/docs/organizations/notifications/includes/opt-out-notification.md @@ -4,32 +4,38 @@ ms.manager: mijacobs ms.author: chcomley author: chcomley ms.topic: include -ms.date: 06/22/2023 +ms.date: 05/13/2025 --- -## Unsubscribe or opt out of a team or out-of-box (OOB) notification subscription +## Unsubscribe (opt out) from team or OOB notification subscription -You can choose to not receive notifications for certain team notification subscriptions by opting out. +You can unsubscribe or opt out of receiving notifications for specific team notification subscriptions, including out-of-the-box (OOB) subscriptions: -::: moniker range="azure-devops" +1. Sign in to your organization (`https://dev.azure.com/`). -1. Sign in to your organization (```https://dev.azure.com/{yourorganization}```). +1. Select **User settings** :::image type="icon" source="../../../media/icons/user-settings-gear.png":::, and then select **Notifications**. -2. Select :::image type="icon" source="../../../media/icons/user-settings-gear.png" border="false"::: **User settings**, and then select **Notifications** from the resulting list. +1. In your list of **Notification** subscriptions, locate the notification you want to disable. - :::image type="content" source="../media/personal-notifications-preview.png" alt-text="Screenshot of personal notifications, preview page."::: +1. To unsubscribe from the notification, move the **State** toggle to the _Off_ position, which changes the toggle color from blue to gray. -3. To unsubscribe from any notification, slide the state **On/Off** indicator to the *Off* position. +The following example shows the user unsubscribed from the "Build completes" notification subscription: -::: moniker-end +:::image type="content" source="../media/unsubscribe-from-build-completes.png" alt-text="Screenshot that shows how to unsubscribe from the Build completes notification subscription by moving the State toggle to the Off position."::: -::: moniker range=" < azure-devops" +> [!NOTE] +> Whether you're an administrator or a regular team member, when you change the **State** value for a shared team notification subscription in your personal settings, the change affects only your personal notifications. The change doesn't affect the setting value of the same shared notification for other team members. -To unsubscribe from any notification, slide the state **On/Off** indicator to the *Off* position. For example, here we turn off the "Build completes" notification subscription. +## Disable work item notifications for project -:::image type="content" source="../media/unsubscribe-from-build-completes.png" alt-text="Screenshot of unsubscribe from Build completes notification subscription."::: +To override organization settings and disable all work item notifications for a project in Azure DevOps, complete the following steps: -::: moniker-end +1. Sign in to your project (`https://dev.azure.com//`). -> [!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. +1. Select **Project settings** > **Notifications**. + +1. In the **Notification** list, select the work notification you want to disable, which highlights the row. + +1. Select **User settings** :::image type="icon" source="../../../media/icons/gear_icon.png"::: and then select **Delivery settings**. + +1. Select **Do not deliver**, and then select **Save**. \ No newline at end of file diff --git a/docs/organizations/notifications/includes/prerequisites-notifications.md b/docs/organizations/notifications/includes/prerequisites-notifications.md new file mode 100644 index 00000000000..043e6c60a4c --- /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: 05/14/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..8fdc4ad064a 100644 --- a/docs/organizations/notifications/manage-team-group-global-organization-notifications.md +++ b/docs/organizations/notifications/manage-team-group-global-organization-notifications.md @@ -1,268 +1,136 @@ --- -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 - Team, Project, Organization +titleSuffix: Azure DevOps +description: Configure email notifications for your team, project, or organization 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: 05/14/2025 monikerRange: '<= azure-devops' +#customer intent: As a developer, I want to set notifications for my team, project, or organization, so I can receive email about changes to source code, git, work items, and builds in Azure DevOps. --- -# Manage notifications for a team, project, or organization +# Manage notifications for your team, project, or organization [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -You can manage email notifications at team, project, and organization levels when changes occur to work items, code reviews, pull requests, source control files, and builds. +You can manage email notifications for your team, project, organization, or collection and receive notifications when changes occur to work items, code reviews, pull requests, source control files, and builds. -For example, when a high priority work item is assigned to your team's area path, a notification email gets sent to the team. For more information, see [Notification types](about-notifications.md#notification-types). +For example, when a high priority work item is assigned to your team's area path, a notification email is sent to the team. For more information, see [Notification types](about-notifications.md#notification-types). ## 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)] -## Create an email subscription - -A subscription lets you control what your team is notified of and how the team receives those notifications. For more information, see [notification types](about-notifications.md#notification-types). - -::: moniker range="azure-devops" - -1. Sign in to your organization (```https://dev.azure.com/{yourorganization}```). -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"::: - -3. Select **New subscription**. - - ![Screenshot of New subscription highlighted.](media/new-subscription-newnav.png) +## Create email subscription -4. Select the type of activity you want your team to be notified of. +A subscription lets you control the activity events that trigger notifications and how the recipients receive the messages. For more information, see [notification types](about-notifications.md#notification-types). - ![Screenshot of select event category and template page.](media/new-sub-page-preview.png) +1. Sign in to your organization (`https://dev.azure.com/`). -1. Provide a description to help you identify the subscription later. +1. Select **Project settings** > **Notifications**: - ![Screenshot of a description provided.](media/new-sub-description.png) + :::image type="content" source="media/nav-team-notifications-hub-newnav.png" border="false" alt-text="Screenshot of the Project Settings, Team Notifications page in Azure DevOps." lightbox="media/nav-team-notifications-hub-newnav.png"::: -1. Choose which team members should receive a notification: +1. On the **Notifications** page for the project, select **New subscription**: - ![Screenshot of Deliver to and Roles dropdown menus.](media/new-sub-team-delivery-by-role.png) + :::image type="content" source="media/new-subscription-newnav.png" alt-text="Screenshot that shows how to select the New subscription option in Azure DevOps." lightbox="media/new-subscription-newnav.png"::: - Choose from one of the following delivery options: +1. Select the **Category** and the **Template** type to use in the new subscription, and then select **Next**. For a list of supported templates, see [Default and supported notifications](oob-built-in-notifications.md). - | **Delivery option** | **Description** | - | --------------------|-------------------| - | **Team members 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. | - | **All team members** | Send an individual email to each member of the team. | - | **SOAP** | Send email notifications to subscribers of SOAP service. | + ::: moniker range="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. + :::image type="content" source="media/new-sub-page-preview.png" alt-text="Screenshot that shows how to select the event category and template page."::: - > [!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. + ::: moniker-end + ::: moniker range="< azure-devops" -2. Choose whether you want to receive notifications about activity in all projects or only a specific project. + :::image type="content" source="media/new-sub-page.png" alt-text="Screenshot that shows how to select the event category and template in earlier versions of Azure DevOps."::: - ![Screenshot of selected scope.](media/new-sub-scope.png) + ::: moniker-end -3. Optionally, configure more filter criteria. +1. Enter a **Description** to help you identify the subscription later: - ![Screenshot of configuring additional filter criteria.](media/new-sub-filter-conditions.png) + :::image type="content" source="media/new-sub-description.png" alt-text="Screenshot that shows how to add a description to help you identify the subscription later."::: -4. Select **Finish** to save the new subscription. +1. Identify which team members should receive a notification: -::: moniker-end + ::: moniker range="azure-devops" -::: moniker range=">= azure-devops-2019 < azure-devops" + :::image type="content" source="media/new-sub-team-delivery-by-role-preview.png" alt-text="Screenshot that shows how to select team members and roles to receive notifications." lightbox="media/new-sub-team-delivery-by-role-preview.png"::: -1. Sign in to your organization (```https://dev.azure.com/{yourorganization}```). -1. Select **Project settings** > **Notifications**. + ::: moniker-end + ::: moniker range="< azure-devops" - :::image type="content" source="media/nav-team-notifications-hub-newnav.png" alt-text="Screenshot of Project settings and Notifications highlighted"::: + :::image type="content" source="media/new-sub-team-delivery-by-role.png" alt-text="Screenshot that shows how to select team members and roles for notifications in earlier versions of Azure DevOps." lightbox="media/new-sub-team-delivery-by-role.png"::: -2. Select **New subscription**. + ::: moniker-end - ![New subscription is highlighted.](media/new-subscription-newnav.png) + 1. Expand the **Deliver to** dropdown list and select the delivery option for the notification: -3. Select the type of activity you want your team to be notified of. + - **Members of \ Team by role**: Only certain team members associated with the event are notified. For example, for work item changes, you might want only the _Current Assignee_ of the work item to receive a notification. - ![Select event category and template.](media/new-sub-page1.png) + - **Team preference**: Use the team's default delivery preference. For more information, see [Manage delivery settings](#manage-global-delivery-settings). -1. Provide a description to help you identify the subscription later. + - **Custom email address**: Send email to a specified email address. - ![Provide a description.](media/new-sub-description.png) + - **Members of \ Team**: Send individual email to each member of the team. + + ::: moniker range="azure-devops" + - **SOAP**: Send email notifications to subscribers of the SOAP service. + ::: moniker-end -1. Choose which team members should receive a notification: + 1. As needed, expand the **Roles** dropdown list and select the checkbox for any applicable role for the message recipients. + + For the **Members of \ Team by role** delivery option, the _Creator_ and _Reviewers_ roles have self-explanatory names. The name of the role matches closely with the role purpose. The other two roles need a bit more explanation: - ![Select role.](media/new-sub-team-delivery-by-role.png) + - The _Changed reviewers_ role applies to any reviewer who is added or deleted as a result of policies defined for the set of files. Suppose a push is made to a pull request and the push introduces a change to the _Task1.cs_ file. If the repo has a policy that requires Person A to review changes to the _Task1.cs_ file, then Person A has the _Changed reviewers_ role for that iteration of the pull request. + + - The _Reset reviewers_ role is related to the "Reset votes" policy. Suppose the same repo has the "Reset votes on new pushes" policy. Also, Person B is set as a required reviewer for the pull request, and they approve the PR. Because the repo defines the "Reset votes" policy, the vote for Person B is reset. As a result, Person B has the _Reset reviewers role_ for this iteration of the pull request. - Choose from one of the following delivery options: + 1. As needed, update the **Skip initiator** option. + + For certain activities, when you select the **Members of \ Team by role** option, you can choose to have the user that initiated the activity receive a notification. This notification is controlled by the **Skip initiator** option. By default, the option is enabled (the box is checked), which means the user that starts the change isn't notified. - | Delivery option | Description | - |--------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| - | **Team members 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. | - | **All team members** | Send an individual email to each member of the team. | + > [!TIP] + > If you don't want to receive a notification for an event you initiated, enable the **Skip initiator** option. For more information, see [Exclude yourself from notification emails for events that you initiate](exclude-self-from-email.md). - 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. +1. For the **Filter** option, specify whether you want to receive notifications for activity in **Any team project** or only **A specific team project**: - > [!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. + :::image type="content" source="media/new-sub-scope.png" alt-text="Screenshot that shows how to specify the scope of the notifications, either any team project or only a specific team project."::: -1. Choose whether you want to receive notifications about activity in all projects or only a specific project. +1. As needed, use the **Filter criteria** section to configure conditional clauses for your notification conditions. For any fields that require a user as a value, such as **Created By**, enter the username or email address of the user. - ![Select scope](media/new-sub-scope.png) - -1. Optionally, configure more filter criteria. - - ![Configure additional filter criteria.](media/new-sub-filter-conditions.png) + :::image type="content" source="media/new-sub-filter-conditions.png" alt-text="Screenshot that shows how to configure other filter criteria." lightbox="media/new-sub-filter-conditions.png"::: 1. 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). - ## Manage global delivery settings -Global notifications apply to all **projects** defined for an organization or collection. -Choose to allow or block delivery of emails for all subscriptions owned by a team or a group. It's a default setting, which applies only if the team or group hasn't explicitly set the option. For more information, see [Global notifications](about-notifications.md#global-notifications). +Global notifications apply to all **projects** defined for an organization or collection. Choose to allow or block delivery of emails for all subscriptions owned by a team or a group. This value is a default setting that applies only if the team or group doesn't explicitly set the option. For more information, see [Global notifications](about-notifications.md#global-notifications). ::: moniker range="azure-devops" > [!TIP] -> 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**](../../organizations/settings/manage-banners.md) that all users see when they sign in. +> Azure DevOps doesn't support organization-wide notifications. An alternate approach is to specify an email distribution list that sends messages to your entire organization. You can also generate a banner with the [**az devops banner command**](../../organizations/settings/manage-banners.md) visible to all users when they sign in. For more information, see [Add and manage information banners in Azure DevOps](../../organizations/settings/manage-banners.md). ::: 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). 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. For more information, see [Configure an SMTP server and customize email for alerts and feedback requests](/azure/devops/server/admin/setup-customize-alerts). You can also generate a banner to communicate 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 [!INCLUDE [opt-out-notification](includes/opt-out-notification.md)] -## Related articles +## Related content -- [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) -- [Change your preferred email address](change-email-address.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) \ No newline at end of file diff --git a/docs/organizations/notifications/manage-your-personal-notifications.md b/docs/organizations/notifications/manage-your-personal-notifications.md index fd6b364631f..91f56bc38a1 100644 --- a/docs/organizations/notifications/manage-your-personal-notifications.md +++ b/docs/organizations/notifications/manage-your-personal-notifications.md @@ -1,22 +1,23 @@ --- -title: Manage personal notification settings +title: Manage Personal Notification Settings titleSuffix: Azure DevOps -description: Get personally notified, when changes occur to source code, git, work items, and builds in Azure DevOps. +description: Set up and manage personal notifications in Azure DevOps and receive messages when changes occur to source code, git, work items, and builds. 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 -ms.date: 06/22/2023 +ms.date: 05/13/2025 monikerRange: '<= azure-devops' +#customer intent: As a developer, I want to manage my personal notifications in Azure DevOps, so I can receive messages when changes occur to source code, git, work items, and builds. --- # Manage your personal notifications [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -You can manage your personal notifications in the following ways: +There are many ways you can manage your personal notifications in Azure DevOps: - View your notifications - Set notifications only for yourself @@ -24,7 +25,7 @@ You can manage your personal notifications in the following ways: - Add a custom notification subscription - Unsubscribe or opt out of a team or project notification subscription -Personal notifications get sent to you in the form of an email as changes occur to builds, code, pipelines, work, artifacts, extensions, releases, and more. +You receive personal notifications as email messages when changes occur to builds, code, pipelines, work, artifacts, extensions, releases, and more. For information about team and project-level notifications, see [Team and project-level notifications](about-notifications.md#team-and-project-level-notifications) and [Manage team or group notifications](manage-team-group-global-organization-notifications.md). @@ -32,168 +33,124 @@ 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 -The following table shows notification event examples. For more information, see a full representation in [About notifications](about-notifications.md#team-and-project-level-notifications). +The following table lists examples of events for which you might receive personal notification email. For more information, see a full representation in [About notifications](about-notifications.md#team-and-project-level-notifications). -| Item | Notification event examples | -|---------------------|---------------------------------------------------------| -| Work item | assigned, unassigned, comments | -| Code reviews | updated, completed | -| Pull request | added or removed reviewer, completion failure, comments | -| Source control file | created, updated | -| Build | completion success, completion failure | +| Category | Notification triggers | +|----------|-----------------------| +| **Work item** | - You're assigned a work item
      - You're unassigned from a work item
      - Comments are added/changed on a work item to which you're assigned | +| **Code reviews** | - A code review to which you're assigned changes
      - A code review to which you're assigned completes | +| **Pull request** | - You're added or removed as a reviewer on a pull request
      - A pull request to which you're assigned fails to build
      - Comments are added/changed on a pull request to which you're assigned | +| **Code under source control** | - A code file is added to a project under version or source control
      - A commit is pushed to a code file under version or source control | +| **Build** | - A build succeeds
      - A build fails | +Follow these steps to view your personal notifications: ::: 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/`). -2. Select :::image type="icon" source="../../media/icons/user-settings-gear.png" border="false"::: **User settings**, and then select **Notifications** from the resulting list. +1. Select **User settings** :::image type="icon" source="../../media/icons/user-settings-gear.png":::, and then select **Notifications**: - :::image type="content" source="media/personal-notifications-preview.png" alt-text="Preview page of personal notifications."::: + :::image type="content" source="media/personal-notifications-preview.png" alt-text="Screenshot that shows how to select the User settings, Notifications option in Azure DevOps."::: -::: moniker-end + Your personal **Notifications** page opens: -::: moniker range=">= azure-devops-2019 < azure-devops" - -1. Sign in to your organization (```https://dev.azure.com/{yourorganization}```). - -2. 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."::: + :::image type="content" source="media/unsubscribe-personal-notifications-preview.png" alt-text="Screenshot showing personal notification subscriptions in Azure DevOps." lightbox="media/unsubscribe-personal-notifications-preview.png"::: ::: moniker-end +::: moniker range="< azure-devops" -::: moniker range=" tfs-2018" - -Open **User settings**, and then select **Notification settings** from the resulting list. +1. Sign in to your organization (`https://dev.azure.com/`). - :::image type="content" source="media/nav-personal-notifications-hub-newnav.png" alt-text="Screenshot showing personal notifications hub."::: +1. Open **User settings**, and then select **Notification settings**: -::: moniker-end - -::: moniker range="tfs-2018" + :::image type="content" source="media/nav-personal-notifications-hub-newnav.png" alt-text="Screenshot that shows how to select the User settings, Notifications option in earlier versions of Azure DevOps."::: -## View and edit all notification subscriptions + Your personal **Notifications** page opens: -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" - -:::image type="content" source="media/unsubscribe-personal-notifications-preview.png" alt-text="Screenshot showing personal notification subscriptions."::: - -::: moniker-end - -::: moniker range=" < azure-devops" - -:::image type="content" source="media/unsubscribe-personal-notifications.png" alt-text="Screenshot of unsubscribe from notification subscriptions."::: + :::image type="content" source="media/unsubscribe-personal-notifications.png" border="false" alt-text="Screenshot showing personal notification subscriptions in earlier versions of Azure DevOps." lightbox="media/unsubscribe-personal-notifications.png"::: ::: moniker-end -::: moniker range=">= tfs-2018" +### Team administrators and recipients -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. +As a team administrator, you can set up a notification subscription that's only for yourself. However, you can ensure that other team members receive specific notifications in the subscription. For each notification setting, you can identify the team recipients to receive the email. -::: moniker-end +## Add custom notification subscription -## Add a custom notification subscription +Custom personal notification subscriptions let you identify precise criteria about events for which you want to receive notifications. You can use custom notification subscriptions to receive messages about any event that occurs in Azure DevOps. -With custom personal notification subscriptions, you can define precise criteria for the events that you want to receive notifications. A custom notification subscription can notify you about any event. Default notification subscriptions differ, as they only notify users or groups directly associated with an event. +Keep in mind that custom notification subscriptions aren't the same as default notification subscriptions. A default notification sends email only to users or groups directly associated with an event. Custom notifications enable you to define the set of message recipients. -::: moniker range=" azure-devops" +1. From your **Notifications** page, select **New subscription**: -1. From your **Notifications** page, select **New subscription**. + ::: moniker range=" azure-devops" -:::image type="content" source="media/manage-personal-notifications-new-subscription-preview.png" alt-text="Screenshot of New notification subscription selected."::: + :::image type="content" source="media/manage-personal-notifications-new-subscription-preview.png" alt-text="Screenshot that shows how to select the New subscription option in Azure DevOps."::: -2. Choose the category and template that you want to use, and then select **Next**. For a list of supported templates, see [Default and supported notifications](oob-built-in-notifications.md). + ::: moniker-end + ::: moniker range=" [!NOTE] - > The fields available for filtering event criteria differ depending on the category and template that you select. For more information about event types, see [Supported event types](oob-supported-event-types.md). + ::: moniker range=" azure-devops" - The new notification subscription appears in the list under the category that you selected. + :::image type="content" source="media/manage-personal-notifications-new-subscription-dialog-preview.png" alt-text="Screenshot that shows how to select the category and template type for a new notification subscription in Azure DevOps."::: - :::image type="content" source="media/manage-personal-notifications-subscription-added-preview.png" alt-text="Screenshot of confirmation of new subscription added."::: + ::: moniker-end + ::: moniker range=" [!NOTE] - > The fields available for filtering event criteria differ depending on the category and template that you select. For more information about event types, see [Supported event types](oob-supported-event-types.md). + > The fields available for filtering event criteria differ depending on the category and template you select. For more information about event types, see [Supported event types](oob-supported-event-types.md). -4. Select **Finish** when you're done. The notification subscription appears on the list under the category that you selected. +1. Select **Finish**. The new notification subscription appears in the list under the category you selected: - :::image type="content" source="media/manage-personal-notifications-subscription-added.png" alt-text="Screenshot showing the notification subscription on the list under its category."::: + ::: moniker range=" azure-devops" -::: moniker-end + :::image type="content" source="media/manage-personal-notifications-subscription-added-preview.png" alt-text="Screenshot that shows the new subscription in the list of personal notification subscriptions in Azure DevOps."::: -::: moniker range="tfs-2018" + ::: moniker-end + ::: 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 + ::: moniker-end [!INCLUDE [opt-out-notification](includes/opt-out-notification.md)] -## Next steps - -> [!div class="nextstepaction"] -> [Use @ mentions in work items and pull requests](at-mentions.md) +## Related content -## Related articles - -- [Manage your personal notifications](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) -- [Change your preferred email address](change-email-address.md) - -### Limitations - -The user interface no longer supports creating plain text email notification subscriptions. +- [Change your preferred email address](change-email-address.md) \ No newline at end of file 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/email-team-delivery-options-new.png b/docs/organizations/notifications/media/email-team-delivery-options-new.png index 656fe888359..fcbaa2a0724 100644 Binary files a/docs/organizations/notifications/media/email-team-delivery-options-new.png and b/docs/organizations/notifications/media/email-team-delivery-options-new.png differ diff --git a/docs/organizations/notifications/media/email-team-delivery-settings.png b/docs/organizations/notifications/media/email-team-delivery-settings.png index 2d493b8fd7f..135b98be414 100644 Binary files a/docs/organizations/notifications/media/email-team-delivery-settings.png and b/docs/organizations/notifications/media/email-team-delivery-settings.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/manage-personal-notifications-complete-pull-request-subscription-preview.png b/docs/organizations/notifications/media/manage-personal-notifications-complete-pull-request-subscription-preview.png index 612bcb920d3..8359f3dab18 100644 Binary files a/docs/organizations/notifications/media/manage-personal-notifications-complete-pull-request-subscription-preview.png and b/docs/organizations/notifications/media/manage-personal-notifications-complete-pull-request-subscription-preview.png differ diff --git a/docs/organizations/notifications/media/manage-personal-notifications-complete-pull-request-subscription.png b/docs/organizations/notifications/media/manage-personal-notifications-complete-pull-request-subscription.png index 8cb12526700..c37deea10d7 100644 Binary files a/docs/organizations/notifications/media/manage-personal-notifications-complete-pull-request-subscription.png and b/docs/organizations/notifications/media/manage-personal-notifications-complete-pull-request-subscription.png differ diff --git a/docs/organizations/notifications/media/manage-personal-notifications-new-subscription-dialog-preview.png b/docs/organizations/notifications/media/manage-personal-notifications-new-subscription-dialog-preview.png index 4e54f6fc42d..f7f18bf2d73 100644 Binary files a/docs/organizations/notifications/media/manage-personal-notifications-new-subscription-dialog-preview.png and b/docs/organizations/notifications/media/manage-personal-notifications-new-subscription-dialog-preview.png differ diff --git a/docs/organizations/notifications/media/manage-personal-notifications-new-subscription-dialog.png b/docs/organizations/notifications/media/manage-personal-notifications-new-subscription-dialog.png index 663897deb49..2efd14b4099 100644 Binary files a/docs/organizations/notifications/media/manage-personal-notifications-new-subscription-dialog.png and b/docs/organizations/notifications/media/manage-personal-notifications-new-subscription-dialog.png differ diff --git a/docs/organizations/notifications/media/manage-personal-notifications-new-subscription-newnav.png b/docs/organizations/notifications/media/manage-personal-notifications-new-subscription-newnav.png index c2d8dc6bd75..4c79d0b18ec 100644 Binary files a/docs/organizations/notifications/media/manage-personal-notifications-new-subscription-newnav.png and b/docs/organizations/notifications/media/manage-personal-notifications-new-subscription-newnav.png differ diff --git a/docs/organizations/notifications/media/manage-personal-notifications-new-subscription-preview.png b/docs/organizations/notifications/media/manage-personal-notifications-new-subscription-preview.png index 540e99823d7..e3929854312 100644 Binary files a/docs/organizations/notifications/media/manage-personal-notifications-new-subscription-preview.png and b/docs/organizations/notifications/media/manage-personal-notifications-new-subscription-preview.png differ diff --git a/docs/organizations/notifications/media/manage-personal-notifications-subscription-added-preview.png b/docs/organizations/notifications/media/manage-personal-notifications-subscription-added-preview.png index 7a5dbcd6657..3d672bf77cd 100644 Binary files a/docs/organizations/notifications/media/manage-personal-notifications-subscription-added-preview.png and b/docs/organizations/notifications/media/manage-personal-notifications-subscription-added-preview.png differ diff --git a/docs/organizations/notifications/media/manage-personal-notifications-subscription-added.png b/docs/organizations/notifications/media/manage-personal-notifications-subscription-added.png index c21c378df6d..127f0f5dcb9 100644 Binary files a/docs/organizations/notifications/media/manage-personal-notifications-subscription-added.png and b/docs/organizations/notifications/media/manage-personal-notifications-subscription-added.png differ diff --git a/docs/organizations/notifications/media/nav-personal-notifications-hub-newnav.png b/docs/organizations/notifications/media/nav-personal-notifications-hub-newnav.png index 48e7c0edaa0..e81b9922a09 100644 Binary files a/docs/organizations/notifications/media/nav-personal-notifications-hub-newnav.png and b/docs/organizations/notifications/media/nav-personal-notifications-hub-newnav.png differ diff --git a/docs/organizations/notifications/media/nav-team-notifications-hub-newnav.png b/docs/organizations/notifications/media/nav-team-notifications-hub-newnav.png index 929f5a28816..3f9dac35f49 100644 Binary files a/docs/organizations/notifications/media/nav-team-notifications-hub-newnav.png and b/docs/organizations/notifications/media/nav-team-notifications-hub-newnav.png differ diff --git a/docs/organizations/notifications/media/nav-ui/organization-notifications-2025.png b/docs/organizations/notifications/media/nav-ui/organization-notifications-2025.png new file mode 100644 index 00000000000..794f695baf0 Binary files /dev/null and b/docs/organizations/notifications/media/nav-ui/organization-notifications-2025.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 deleted file mode 100644 index c470a77aa70..00000000000 Binary files a/docs/organizations/notifications/media/nav-ui/organization-notifications-s172.png and /dev/null differ diff --git a/docs/organizations/notifications/media/new-sub-description.png b/docs/organizations/notifications/media/new-sub-description.png index 2c2899b7afc..e31e89e6a4f 100644 Binary files a/docs/organizations/notifications/media/new-sub-description.png and b/docs/organizations/notifications/media/new-sub-description.png differ diff --git a/docs/organizations/notifications/media/new-sub-filter-conditions.png b/docs/organizations/notifications/media/new-sub-filter-conditions.png index 54a93752878..21965b2ffd9 100644 Binary files a/docs/organizations/notifications/media/new-sub-filter-conditions.png and b/docs/organizations/notifications/media/new-sub-filter-conditions.png differ diff --git a/docs/organizations/notifications/media/new-sub-page-preview.png b/docs/organizations/notifications/media/new-sub-page-preview.png index 61f6646706c..98ba07d67fb 100644 Binary files a/docs/organizations/notifications/media/new-sub-page-preview.png and b/docs/organizations/notifications/media/new-sub-page-preview.png differ diff --git a/docs/organizations/notifications/media/new-sub-page.png b/docs/organizations/notifications/media/new-sub-page.png new file mode 100644 index 00000000000..193e29315e0 Binary files /dev/null and b/docs/organizations/notifications/media/new-sub-page.png differ diff --git a/docs/organizations/notifications/media/new-sub-page1.png b/docs/organizations/notifications/media/new-sub-page1.png deleted file mode 100644 index 09e874ff269..00000000000 Binary files a/docs/organizations/notifications/media/new-sub-page1.png and /dev/null differ diff --git a/docs/organizations/notifications/media/new-sub-scope.png b/docs/organizations/notifications/media/new-sub-scope.png index 2866ac64ede..391b25f2be2 100644 Binary files a/docs/organizations/notifications/media/new-sub-scope.png and b/docs/organizations/notifications/media/new-sub-scope.png differ diff --git a/docs/organizations/notifications/media/new-sub-team-delivery-by-role-preview.png b/docs/organizations/notifications/media/new-sub-team-delivery-by-role-preview.png new file mode 100644 index 00000000000..d9487e34ee0 Binary files /dev/null and b/docs/organizations/notifications/media/new-sub-team-delivery-by-role-preview.png differ diff --git a/docs/organizations/notifications/media/new-sub-team-delivery-by-role.png b/docs/organizations/notifications/media/new-sub-team-delivery-by-role.png index 525e39132c7..7efef6d8a1f 100644 Binary files a/docs/organizations/notifications/media/new-sub-team-delivery-by-role.png and b/docs/organizations/notifications/media/new-sub-team-delivery-by-role.png differ diff --git a/docs/organizations/notifications/media/new-subscription-newnav.png b/docs/organizations/notifications/media/new-subscription-newnav.png index c5ae6811390..c96454a9dfb 100644 Binary files a/docs/organizations/notifications/media/new-subscription-newnav.png and b/docs/organizations/notifications/media/new-subscription-newnav.png differ diff --git a/docs/organizations/notifications/media/notification-turned-off.png b/docs/organizations/notifications/media/notification-turned-off.png index 9bb58604e5c..d65a98cea91 100644 Binary files a/docs/organizations/notifications/media/notification-turned-off.png and b/docs/organizations/notifications/media/notification-turned-off.png differ diff --git a/docs/organizations/notifications/media/notifications-default.png b/docs/organizations/notifications/media/notifications-default.png new file mode 100644 index 00000000000..174eaea4675 Binary files /dev/null and b/docs/organizations/notifications/media/notifications-default.png differ diff --git a/docs/organizations/notifications/media/notifications-turned-on.png b/docs/organizations/notifications/media/notifications-turned-on.png index 24661e41709..0659bc6854a 100644 Binary files a/docs/organizations/notifications/media/notifications-turned-on.png and b/docs/organizations/notifications/media/notifications-turned-on.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/open-profile-menu-notifications-2020.png b/docs/organizations/notifications/media/personal/open-profile-menu-notifications-2020.png deleted file mode 100644 index 946782dff39..00000000000 Binary files a/docs/organizations/notifications/media/personal/open-profile-menu-notifications-2020.png and /dev/null differ diff --git a/docs/organizations/notifications/media/personal/open-user-notifications.png b/docs/organizations/notifications/media/personal/open-user-notifications.png new file mode 100644 index 00000000000..17a9dcaeb4a Binary files /dev/null and b/docs/organizations/notifications/media/personal/open-user-notifications.png differ diff --git a/docs/organizations/notifications/media/personal/user-notifications-page.png b/docs/organizations/notifications/media/personal/user-notifications-page.png new file mode 100644 index 00000000000..5a081f87016 Binary files /dev/null and b/docs/organizations/notifications/media/personal/user-notifications-page.png differ diff --git a/docs/organizations/notifications/media/personal/user-notifications.png b/docs/organizations/notifications/media/personal/user-notifications.png deleted file mode 100644 index ef165113582..00000000000 Binary files a/docs/organizations/notifications/media/personal/user-notifications.png and /dev/null 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/media/unsubscribe-from-build-completes.png b/docs/organizations/notifications/media/unsubscribe-from-build-completes.png index ac43faefa31..37c0410129e 100644 Binary files a/docs/organizations/notifications/media/unsubscribe-from-build-completes.png and b/docs/organizations/notifications/media/unsubscribe-from-build-completes.png differ diff --git a/docs/organizations/notifications/media/unsubscribe-personal-notifications.png b/docs/organizations/notifications/media/unsubscribe-personal-notifications.png index 3f64873fb34..33d074bdab0 100644 Binary files a/docs/organizations/notifications/media/unsubscribe-personal-notifications.png and b/docs/organizations/notifications/media/unsubscribe-personal-notifications.png differ diff --git a/docs/organizations/notifications/navigating-the-ui.md b/docs/organizations/notifications/navigating-the-ui.md index 6cc8070f61f..13e3df2aac8 100644 --- a/docs/organizations/notifications/navigating-the-ui.md +++ b/docs/organizations/notifications/navigating-the-ui.md @@ -1,148 +1,83 @@ --- -title: Navigate the notifications UI +title: Navigate the Notifications UI titleSuffix: Azure DevOps -description: Go to and explore the notifications pages in Azure DevOps. +description: Explore the notifications pages in Azure DevOps, including personal status, team and project-level status, and global settings. ms.subservice: azure-devops-notifications ms.custom: quarterly-update ms.reviewer: wismythe ms.author: chcomley author: chcomley -ms.topic: conceptual -monikerRange: '<= azure-devops' -ms.date: 06/22/2023 +ms.topic: concept-article +ms.date: 05/06/2025 +#customer intent: As a developer, I want to view notifications in Azure DevOps, so I can check the status of notifications for myself, my team or project, and also global settings. --- # Access notification settings [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -Learn about navigating the notifications user interface. - -> [!NOTE] -> This article applies to Azure DevOps, TFS 2017 Update 1 and later versions. For information on TFS 2017 and earlier versions, see [Manage personal notifications](manage-your-personal-notifications.md) and select the TFS 2015 content version. - -## Notifications settings - -You can set notifications at the following levels: +This article describes how to navigate the **Notifications** user interface in Azure DevOps. You can set notifications at the following levels: * Personal * Team * Project * Organization or collection (organization for the cloud and project collection for on-premises) -[!INCLUDE [note-smtp-server](includes/note-smtp-server.md)] - ## 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). - -For more permission settings regarding notifications, see [Permissions and groups, Notifications or alerts](../../organizations/security/permissions.md#notifications-or-alerts). +[!INCLUDE [prerequisites-project-member-only](../../includes/prerequisites-project-member-only.md)] -       + ## Open your personal notifications -::: moniker range="azure-devops" - -Open your :::image type="icon" source="../../media/icons/user-settings-gear.png" border="false"::: profile menu, and then choose **Notifications** or **Notification settings**. +To open your personal notifications, select the **User settings** icon :::image type="icon" source="../../media/icons/user-settings-gear.png"::: in Azure DevOps, and then select **Notifications** or **Notification settings**: -:::image type="content" source="media/personal/user-notifications.png" alt-text="View your personal notifications page"::: +:::image type="content" source="media/personal/open-user-notifications.png" alt-text="Screenshot that shows how to open your personal notifications page in Azure DevOps."::: -::: moniker-end +The **User settings > Notifications** page opens: -::: moniker range="< azure-devops" -Open your profile menu and choose **Notification settings**. -::: moniker-end -::: moniker range=">= azure-devops-2019 < azure-devops" -:::image type="content" source="media/personal/open-profile-menu-notifications-2020.png" alt-text="Select your profile menu, and Notification settings"::: -::: moniker-end -::: moniker range="tfs-2018" -> [!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 +:::image type="content" source="media/personal/user-notifications-page.png" alt-text="Screenshot of the User settings, Notifications page in Azure DevOps."::: For more information, see [Manage your notifications](manage-your-personal-notifications.md) - + -## Open team or project level notifications +## Open notifications for a team or project -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. +To open a team or project-level notifications page, enter the following URL in the browser address field. Replace the `` and `` portions with your organization and project name. ```URL -https://dev.azure.com/{organization}/{project}/_settings/notifications +https://dev.azure.com///_settings/notifications ``` -> [!div class="mx-imgBorder"] -> ![Screenshot of 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" +The **Project settings > Notifications** page opens: -1. Enter the following URL to reach the organization-level notifications page, replacing *OrganizationName* with your organization's name. +:::image type="content" source="media/nav-team-notifications-hub-newnav.png" alt-text="Screenshot of the Project Settings, Team Notifications page in Azure DevOps."::: - ```URL - https://dev.azure.com/OrganizationName/_settings/notifications - ``` +For more information, see [Manage notifications for a team or group](manage-team-group-global-organization-notifications.md). - Or, choose :::image type="icon" source="../../media/icons/project-icon.png" border="false"::: **Azure DevOps**, and then choose **Organization settings**. + - :::image type="content" source="../../media/settings/open-org-settings-s172.png" alt-text="Open Organization settings"::: - -2. Choose **Global notifications**. - - :::image type="content" source="media/nav-ui/organization-notifications-s172.png" alt-text="Open Global Notifications"::: - -::: moniker-end - -::: moniker range=">= azure-devops-2019 < azure-devops" - -Enter the following URL to reach the organization-level notifications page, replacing *ServerName* and *CollectionName* with your instance name. - -1. Enter the following URL to reach the organization-level notifications page, replacing *OrganizationName* with your organization's name. - - ```URL - http://ServerName/CollectionName/_settings/notifications?view=defaultSubscriptions - ``` - - Or, choose :::image type="icon" source="../../media/icons/project-icon.png" border="false"::: **Azure DevOps**, and then choose **Collection settings**. - - :::image type="content" source="../../media/settings/open-collection-settings-2020.png" alt-text="Open Collection settings"::: - -2. Choose **Global Notifications**. +## Open Global notifications - :::image type="content" source="media/nav-ui/collection-notifications-2020.png" alt-text="Select to open Global Notifications"::: +To open the settings for **Global notifications**, select :::image type="icon" source="../../media/icons/project-icon.png"::: **Azure DevOps**, and then select **Organization settings**: -::: moniker-end +:::image type="content" source="../../media/settings/open-organization-settings-2025.png" alt-text="Screenshot that shows how to open the Organization settings page in Azure DevOps by first selecting the product icon."::: -::: moniker range="tfs-2018" +You can also enter the following URL to reach the organization-level notifications page. Replace the `` portion with your organization name. ```URL -https://dev.azure.com/{organization}/_admin/_notifications +https://dev.azure.com//_settings/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."::: +On the **Organization Settings** page, select **Global notifications**: -::: moniker-end +:::image type="content" source="./media/nav-ui/organization-notifications-2025.png" alt-text="Screenshot that shows how to open the Global notifications page in Azure DevOps by using a URL for your organization."::: For more information, see [Manage team and Global notifications](manage-team-group-global-organization-notifications.md) -## Related articles +## Related content -- [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) +- [Follow a specific work item](../../boards/work-items/follow-work-items.md) - [Change your preferred email address](change-email-address.md) \ No newline at end of file diff --git a/docs/organizations/notifications/oob-built-in-notifications.md b/docs/organizations/notifications/oob-built-in-notifications.md index 2cd8c7d54e9..ea4dd1c9f9b 100644 --- a/docs/organizations/notifications/oob-built-in-notifications.md +++ b/docs/organizations/notifications/oob-built-in-notifications.md @@ -1,84 +1,122 @@ --- -title: Default and supported notifications +title: Default and Supported Notifications titleSuffix: Azure DevOps -description: Learn about out of the box or default notifications set in Azure DevOps. +description: "Learn about out of the box or default notifications set in Azure DevOps: build or release, code under Git or TFVC source control, extension management, and work items." ms.subservice: azure-devops-notifications ms.custom: cross-project -ms.topic: conceptual +ms.topic: concept-article toc: show ms.author: chcomley author: chcomley -ms.date: 12/20/2019 -monikerRange: '<= azure-devops' +ms.date: 05/05/2025 +#customer intent: As a developer, I want to know the out of the box or default notifications for events in Azure DevOps, so I can set up notifications for my projects in Azure DevOps. --- # Default and supported notifications [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -Configure default subscriptions to send notifications to certain roles or user groups with specific associations to an event. For example, "reviewer" is a role on a pull request event. "Assignee (current)" is a role that reflects the current Assigned To user of a changed work item. +You can configure default subscriptions to send notifications to certain roles or user groups with specific associations to an event. Some examples include users who are assigned the _Reviewer_ role on a pull request, or the _Assignee (current)_ role that identifies the current **Assigned To** user of a changed work item. -In the description of the default subscription, you can see the roles that receive notifications. For example, *"Notifies you when a build you queued or that was queued for you completes"*. Role-based subscriptions contain a Roles field that you can view by opening the subscription. Only users or groups that belong to the role listed within the subscription receive a notification for an event matched by the subscription. +In the description of the default subscription, you can see the roles that receive notifications, such as _"Notifies you when a build you queued or that was queued for you completes."_ Role-based subscriptions contain a **Roles** field that you can view by opening the subscription. Only users or groups that belong to the role listed within the subscription receive a notification for an event matched by the subscription. -Default subscriptions only send targeted notifications. That is, the recipient is always somehow associated with the event that triggered the notification. For example, the default subscription for work item updates only sends an email notification to the person assigned to the work item. +Default subscriptions only send targeted notifications. The recipient is always somehow associated with the event that triggers the notification. For example, the default subscription for work item updates only sends an email notification to the user assigned to the work item. ## Out-of-the-box (OOB) or default subscriptions -The following events send notifications to all subscribers, by default. For more information about unsubscribing from a notification, see [Unsubscribe from a notification](unsubscribe-default-notification.md). - -Within the personal notifications page, OOB subscriptions appear with the following image: ![Notification](media/oob-notification.png). - - -| Category | Type| Build| Description -|-----------------------|-------------------|---------------------|----------------| -| Build |Build completed |Build completes |Notifies you when a build you queued or that was queued for you completes| -| Code (Git)| Pull request | Pull request reviewers added or removed | Notifies you when you or another user gets added or removed from a pull request that you created| -| Code (Git)| Pull request| Pull request completion failures | Notifies you when a pull request you created fails to complete | -| Code (Git)| Pull request| Pull request changes | Notifies you when changes are made to a pull request you created or are a reviewer for | -| Code (Git)| Pull request comment| A comment is left on a pull request | Notifies you about comments made to a pull request that you created or a discussion you're involved in | -| Code (TFVC)| Code review | A code review I'm working on changes | Notifies you when a change is made to a code review you're assigned to| -| Extension management| Extension| Extensions have been modified. | Extensions have been modified. | -| Extension management| Extension request (batch) | Extensions are requested or requests are updated. | Extensions are requested or requests are updated. | -| Release| Deployment pending | Manual intervention pending | Notifies you when a manual intervention is pending on you | -| Release| Deployment completed | Deployment to an owned environment failed | Notifies you when a deployment to an environment you own fails to complete successfully and makes the environment unhealthy | -| Release| Deployment completed | Deployment to an approved environment failed | Notifies you when a deployment you approved fails to complete successfully and makes the environment unhealthy | -| Release| Deployment completed| Deployment completion failures | Notifies you when a deployment you requested fails to complete successfully and makes the environment unhealthy | -| Release| Release approval pending| Deployment approval pending| Notifies you when an approval for a deployment is pending on you | -| Work| Work item| A work item is moved from this project | Notifies you when the area path for a work item is moved to another project | -| Work | Work item | A work item assigned | Notifies you when you get assigned or unassigned a work item | +The following sections list the events send notifications available to all subscribers, by default. For more information about unsubscribing from a notification, see [Unsubscribe from a notification](unsubscribe-default-notification.md). + +In the personal notifications page, the globe icon :::image type="icon" source="media/oob-notification.png"::: indicates an OOB subscription. + +### Build events + +The following OOB event types are supported by default for the project **Build** category in Azure DevOps: + +|Event type |Trigger |Description | +|-----------|--------|------------| +| **Build completed** | Build completes | Notifies you when a build you queued or that was queued for you completes. | + +### Code events for Git + +The following OOB event types are supported by default for the **Code (Git)** category in Azure DevOps. These notification types apply to your project code under source control with Git. + +|Event type |Trigger |Description | +|-----------|--------|------------| +| **Pull request** | Pull request reviewers added or removed | Notifies you when you or another user gets added or removed from a pull request that you created. | +| **Pull request** | Pull request completion failures | Notifies you when a pull request you created fails to complete. | +| **Pull request** | Pull request changes | Notifies you when changes are made to a pull request you created, or changes are made to a pull request for which you're assigned as a reviewer. | +| **Pull request comment** | Comment added to pull request | Notifies you about comments added to a pull request that you created, or a discussion you're involved in. | + +### Code events for TFVC + +The following OOB event types are supported by default for the **Code (TFVC)** category in Azure DevOps. These notification types apply to your project code under control with Team Foundation Version control (TFVC). + +|Event type |Trigger |Description | +|-----------|--------|------------| +| **Code review** | Changes to code review that you're working on | Notifies you when a change is made to a code review you're assigned to. | + +### Extension management events + +The following OOB event types are supported by default for the project **Extension management** category in Azure DevOps. + +|Event type |Trigger |Description | +|-----------|--------|------------| +| **Extension** | Extensions modified | Notifies you when extensions are modified. | +| **Extension request (batch)** | Extensions requested, or existing requests updated | Notifies you when extensions are requested or existing requests are updated. | + +### Release events + +The following OOB event types are supported by default for the project **Release** category in Azure DevOps: + +|Event type |Trigger |Description | +|-----------|--------|------------| +| **Deployment pending** | Manual intervention pending | Notifies you when a manual intervention is pending on your input. | +| **Deployment completed** | Deployment to owned environment failed | Notifies you when a deployment to an environment you own fails to complete successfully and makes the environment unhealthy. | +| **Deployment completed** | Deployment to approved environment failed | Notifies you when a deployment you approved fails to complete successfully and makes the environment unhealthy. | +| **Deployment completed** | Deployment completion failures | Notifies you when a deployment you requested fails to complete successfully and makes the environment unhealthy. | +| **Release approval pending** | Deployment approval pending | Notifies you when an approval for a deployment is pending on your input. | + +### Work (work items) events + +The following OOB event types are supported by default for the project **Work** category in Azure DevOps. + +|Event type |Trigger |Description | +|-----------|--------|------------| +| **Work item** | Work item moved from this project (area path changed) | Notifies you when the area path for a work item is moved to another project. | +| **Work item** | Work item assigned | Notifies you when you're assigned or unassigned a work item. | ## Supported subscriptions -You can create subscriptions using the following templates for yourself, a team, or a group. Within the subscription dialog, you can specify additional fields based on the category. For more information, see [Manage personal notifications](manage-your-personal-notifications.md). - -| Category | Template | -|-----------------------|-------------------| -|Build | A build completes | -|Build | A build fails | -|Build | A build controller or agent's status changes | -|Build | A build's quality changes | -|Code (Git)| A commit authored by me is pushed | -|Code (Git)| A commit is pushed by me | -|Code (Git)| A commit is pushed | -|Code (Git)| A pull request is created or updated | -|Code (TFVC)| Code is checked in | -|Code (TFVC)| Code is checked in with a policy override | -|Code (TFVC)| A file with a specific extension is checked in | -|Code (TFVC)| A file under a specific path is checked in | -|Code (TFVC)| A code review I'm working on changes | -|Work | A work item I created is changed | -|Work | A work item assigned to me is changed | -|Work | A work item is changed | -|Work | A work item is assigned to me | -|Work | A work item is deleted | -|Work | A work item is restored | -|Extension management | An extension is modified | -|Release | An approval for a deployment is pending | -|Release | A deployment is completed | -|Release | A manual intervention for a deployment is pending | - -## Related articles - -- [About notifications](about-notifications.md) -- [Manage personal notifications](./manage-team-group-global-organization-notifications.md) +You can create subscriptions by using the following templates for yourself, a team, or a group. Within the subscription dialog, you can specify other fields based on the category. For more information, see [Manage personal notifications](manage-your-personal-notifications.md). + +|Category |Template description | +|---------|---------------------| +| **Build** | A build completes. | +| **Build** | A build fails. | +| **Build** | The status changes for a build controller or agent. | +| **Build** | The quality changes for a build. | +| **Code (Git)** | A commit authored by you is pushed. | +| **Code (Git)** | You push a commit. | +| **Code (Git)** | A commit is pushed. | +| **Code (Git)** | A pull request is created or updated. | +| **Code (TFVC)** | Code is checked in. | +| **Code (TFVC)** | Code is checked in with a policy override. | +| **Code (TFVC)** | A file with a specific extension is checked in. | +| **Code (TFVC)** | A file under a specific path is checked in. | +| **Code (TFVC)** | A code review that you're working on changes. | +| **Work** | A work item that you created is changed.| +| **Work** | A work item assigned to you is changed. | +| **Work** | A work item is changed. | +| **Work** | A work item is assigned to you. | +| **Work** | A work item is deleted. | +| **Work** | A work item is restored. | +| **Extension management** | An extension is modified. | +| **Release** | An approval for a deployment is pending. | +| **Release** | A deployment is completed. | +| **Release** | A manual intervention for a deployment is pending. | + +## Related content + +- Learn [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 diff --git a/docs/organizations/notifications/oob-supported-event-types.md b/docs/organizations/notifications/oob-supported-event-types.md index 6a085168f8b..fcf4060ccd6 100644 --- a/docs/organizations/notifications/oob-supported-event-types.md +++ b/docs/organizations/notifications/oob-supported-event-types.md @@ -1,31 +1,69 @@ --- -title: Event types for notifications subscriptions +title: Event Types for Notifications Subscriptions titleSuffix: Azure DevOps -description: List of supported event types to set up automatic notifications in Azure DevOps. +description: "Review supported event types for automatic notifications in Azure DevOps: build or release, code under Git or TFVC source control, and work items." ms.subservice: azure-devops-notifications -ms.topic: conceptual +ms.topic: concept-article toc: show ms.author: chcomley author: chcomley -ms.date: 12/30/2019 +ms.date: 05/05/2025 monikerRange: '<= azure-devops' +#customer intent: As a developer, I want to know the supported event types, so I can set up automatic notifications for my projects in Azure DevOps. --- # Supported event types [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -Learn the supported event types for notification subscriptions in Azure DevOps. - -| Category | Type | Fields| Roles| -|-----------|-----------|---------|---| -|Build|Completed|Build controller
      Build reason
      Compilation status
      Definition name
      Requested by
      Requested for
      Status
      Team project
      Test status|Last changed by
      Requested by
      Requested for
      Deleted by| -|Build|Status changed|Changed by
      Changed time
      Quality
      Team project| | -|Code (Git)|Push|Authored by
      Branches updated
      Changes in folder
      Comment
      Committed by
      Pushed by
      Repository name
      Team project|Pushed by| -|Code (Git)|Pull request|Changed by
      Changes in folder
      Code under review
      Created by
      Event type
      Policy Bypass
      Repository name
      Reviewers
      Source branch name
      Status
      Target branch name
      Team project
      Vote|Creator
      Reviewers
      Changed reviewers
      Reset reviewers| -|Code (TFVC)|Check in|Associated work item
      Comment
      Committer
      File extension
      File name
      Folder path
      Policy override comment
      Server item
      Team project|Committer
      Owner| -|Code (TFVC)|Code review|Area path
      Changed by
      Closing comment
      Comment
      My review status
      Requested by
      Review action
      Review context type
      Review owner
      Reviewed item file name
      Reviewed item parent path
      Reviewers
      State
      Team project
      Work item ID|Requested by
      New reviewers
      Reviewers
      Declined reviewers| -|Work item|Created
      Changed
      Deleted
      Restored|Any work item field|Assigned to (new)
      Assigned to (previous)
      Assigned to (current)
      Changed by
      Created by
      Authorized as| -|Release|Release approval pending|Approval Type
      Assigned To
      Environment Name
      Release Definition Name|Assigned to
      Environment owner| -|Release|Deployment completed|Deployment request reason
      Deployment requested for
      Deployment Status
      Environment Name
      Environment Owner
      Last Deployment Status
      Release Definition Name
      Release request reason
      Release requested by|Deployment requested for
      Environment owner
      Release requested by
      Approved by| -|Release|Deployment pending|Environment Name
      Environment Owner
      Release Definition Name|Manual intervention recipient
      Environment owner| +This reference article identifies the supported event types for notification subscriptions in Azure DevOps. The following sections list the event types by project notification category, including Build, Release, Work items, and Code under Git source control or Team Foundation version control (TFVC). + +## Build events + +The following event types are supported for the project **Build** category in Azure DevOps: + +|Event type |Fields |Roles | +|-----------|-------|------| +| **Completed** | Build controller
      Build reason
      Compilation status
      Definition name
      Requested by
      Requested for
      Status
      Team project
      Test status | _Last changed by_
      _Requested by_
      _Requested for_
      _Deleted by_ | +| **Status changed** |Changed by
      Changed time
      Quality
      Team project | (not available) | + +## Code events for Git + +The following event types are supported for the **Code (Git)** category in Azure DevOps. These notification types apply to your project code under source control with Git. + +|Event type |Fields |Roles | +|-----------|-------|------| +| **Push** | Authored by
      Branches updated
      Changes in folder
      Comment
      Committed by
      Pushed by
      Repository name
      Team project | _Pushed by_ | +| **Pull request** | Changed by
      Changes in folder
      Code under review
      Created by
      Event type
      Policy Bypass
      Repository name
      Reviewers
      Source branch name
      Status
      Target branch name
      Team project
      Vote | _Creator_
      _Reviewers_
      _Changed reviewers_
      _Reset reviewers_ | + +## Code events for TFVC + +The following event types are supported for the **Code (TFVC)** category in Azure DevOps. These notification types apply to your project code under control with Team Foundation Version control (TFVC). + +|Event type |Fields |Roles | +|-----------|-------|------| +| **Check in** | Associated work item
      Comment
      Committer
      File extension
      File name
      Folder path
      Policy override comment
      Server item
      Team project | _Committer_
      _Owner_ | +| **Code review** | Area path
      Changed by
      Closing comment
      Comment
      My review status
      Requested by
      Review action
      Review context type
      Review owner
      Reviewed item file name
      Reviewed item parent path
      Reviewers
      State
      Team project
      Work item ID | _Requested by_
      _New reviewers_
      _Reviewers_
      _Declined reviewers_ | + +## Work item events + +The following event types are supported for the project **Work items** category in Azure DevOps. + +|Event type |Fields |Roles | +|-----------|-------|------| +| **Created**
      **Changed**
      **Deleted**
      **Restored** | Any work item field | _Assigned to (new)_
      _Assigned to (previous)_
      _Assigned to (current)_
      _Changed by_
      _Created by_
      _Authorized as_ | + +## Release events + +The following event types are supported for the project **Release** category in Azure DevOps: + +|Event type |Fields |Roles | +|-----------|-------|------| +| **Release approval pending** | Approval Type
      Assigned To
      Environment Name
      Release Definition Name | _Assigned to_
      _Environment owner_ | +| **Deployment completed** | Deployment request reason
      Deployment requested for
      Deployment Status
      Environment Name
      Environment Owner
      Last Deployment Status
      Release Definition Name
      Release request reason
      Release requested by | _Deployment requested for_
      _Environment owner_
      _Release requested by_
      _Approved by_ | +| **Deployment pending** | Environment Name
      Environment Owner
      Release Definition Name | _Manual intervention recipient_
      _Environment owner_ | + +## Related content + +- Review [default and supported notifications](oob-built-in-notifications.md) +- [Manage notifications for a team, project, or organization](manage-team-group-global-organization-notifications.md) \ No newline at end of file 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..63d515f4d61 100644 --- a/docs/organizations/notifications/troubleshoot-not-getting-email.md +++ b/docs/organizations/notifications/troubleshoot-not-getting-email.md @@ -1,87 +1,110 @@ --- -title: Why am I not receiving notification emails? +title: Troubleshoot Not Receiving Notification Emails titleSuffix: Azure DevOps -description: Discover why you aren't receiving emails from your Azure DevOps notification subscriptions and fix it. +description: Discover why you aren't receiving emails from your Azure DevOps notification subscriptions and fix the problem. ms.subservice: azure-devops-notifications ms.custom: quarterly-update ms.reviewer: wismythe ms.author: chcomley author: chcomley -ms.topic: conceptual -ms.date: 06/16/2021 -monikerRange: '<= azure-devops' +ms.topic: troubleshooting-general +ms.date: 05/07/2025 +#customer intent: As a developer, I want to troubleshoot why I'm not receiving emails from my notifications or subscriptions so I can fix the problem. --- # Not getting emails from subscriptions or notifications [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -An email is sent when an [event](oob-supported-event-types.md) occurs that matches a notification subscription. For more information about notification subscriptions, see the [notifications overview](about-notifications.md). +This article provides troubleshooting information to help you address why you might not be receiving an expected subscription or notification email. An email is sent when an [event](oob-supported-event-types.md) occurs that matches a notification subscription. For more information about notification subscriptions, see the [notifications overview](about-notifications.md). -Learn why you may not be receiving an expected subscription or notification email. - -If you're not receiving an expected notification email, it could be for one of the following reasons. +If you're not receiving an expected notification email, here are some possible causes: * The email server is down, unreachable, or rejected authenticated. -* The email was delivered to an unchecked folder -* The subscription is disabled or opted-out -* The event doesn't match the specified subscription filter conditions -* The subscription is defined to not send emails to the initiator of an event -* The organization level _do not deliver_ setting is impacting email delivery -* The team or group level [_do not deliver_](#check-do-not-deliver-setting-for-your-team-or-group) setting is impacting email delivery -* You're not a member of the group or team receiving the email -* 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 +* The email is delivered to an unchecked folder. +* The subscription is disabled or opted-out. +* The event doesn't match the specified subscription filter conditions. +* The subscription is defined to not send emails to the initiator of an event. +* The **Do not deliver** setting at the organization, team, or group level is impacting email delivery. +* You're not a member of the group or team receiving the email. +* You're a member of a Windows Server Active Directory (Windows AD) group and the subscription contains an `@Me` mention 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 + +The following sections describe possible solutions to resolve the issue of missing notification emails. + +### Check other email folders + +Personal or organizational email rules can affect message delivery and change the target folder. Ensure the expected email isn't delivered to a different email folder, including the Junk or Deleted Items folders. + +### Confirm subscription is enabled + +Different **Notification** settings and configuration scenarios can disable a subscription. Make sure the subscription is enabled as expected. In your personal subscriptions, locate the subscription for which you're expecting to receive the email. For more information, see [Open your personal subscriptions](navigating-the-ui.md#open-person-level). + +Azure DevOps displays a disabled subscription as grayed (not available) in the **Notification** settings user interface. The following screenshot shows an example with two subscriptions, where the first subscription is enabled and the second is disabled: + +:::image type="content" source="media/subscription-disabled.png" alt-text="Screenshot that shows the visual difference for an enabled and a disabled subscription in Azure DevOps."::: + +Here are some scenarios where a subscription might not be available: + +- 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. +- A _custom_ subscription disables when an administrator disables the subscription at the organization or team level, or if you disable a personal custom subscription. + +### Inspect subscription filter conditions -Complete the following tasks to determine if any resolve the issue. +Filter conditions can prevent the system from generating the email, or cause you not to receive the email. The system only generates an email if an Azure DevOps Services event matches _all_ filter conditions for the subscription. -## Check other email folders +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 match the Azure DevOps Services event. -Ensure the email wasn't delivered to a different email folder, including the junk folder. +### Check 'Skip initiator' option -## Locate the subscription and ensure it's enabled +When the **Skip initiator** option is set on a subscription, the system excludes the initiator of the Azure DevOps Services event from the email recipient list, while all others receive the event. -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). +Consider a subscription for a _work item changed_ event. You might set the **Skip initiator** option to avoid receiving email for changes you make to the work item. For more information, see [Exclude yourself from notification emails of events you started](exclude-self-from-email.md). -If the subscription is grayed-out in the user interface, then it's disabled. The following screenshot shows the first subscription enabled and the second disabled. +### Check 'Do not deliver' setting for organization -> [!div class="mx-imgBorder"] ->![subscription disabled](media/subscription-disabled.png) +Similar to the **Skip initiator** option, the **Do not deliver** setting can also interfere with message delivery. On the organization-level notifications page, select **Settings**, and check the **Do not deliver** setting. For more information, see [Manage notifications for a team, project, or organization](manage-team-group-global-organization-notifications.md). -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. +When the [delivery setting](#check-do-not-deliver-setting-for-team-or-group) is **Do not deliver**, all teams or groups that don't explicitly specify the delivery option inherit the **Do not deliver** setting. This setting alone doesn't necessarily indicate an email isn't delivered, but it can contribute to the problem. -## Closely inspect subscription filter conditions +After you check the delivery setting at the organizational, see if a group or team delivery setting inherits the value and blocks delivery to your group or team. -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 'Do not deliver' setting for team or group -## Check the "Skip initiator" option +When a team or group specifies the **Deliver to individual members** setting, other groups within the same team or group might specify different delivery settings. Conflicts can arise when the system encounters different values for the setting at various levels within the membership hierarchy. For more information about membership inheritance, and how to send email only to specific members, see [Determine recipients of notification emails](concepts-email-recipients.md). -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). +### Confirm contact email address -## Check "Do not deliver" setting for organization +Your preferred email address for the subscription might not be the same address you're waiting on for delivery of the notifications. Your contact email address is a user profile setting. Verify that your contact address is the same address for which you're expecting to receive email. -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. +To see your contact email address, hover over the **User settings** icon :::image type="icon" source="../../media/icons/user-settings-gear.png"::: and select **Profile**. Check the value of the **Contact email** setting. For more information, see [Set user preferences](../../organizations/settings/set-your-preferences.md). -## Check "Do not deliver" setting for your team or group +### Verify @Me filter expansion for teams or groups -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). +When the subscription or notifications configuration uses an `@Me` filter clause, the system expands the filter to locate matches in the recipient address list. However, Windows AD groups aren't expanded for filter matching. If you specify email addresses for team or group members by using Windows AD groups, these members don't receive the notification emails. -## Check your configured email address +Specify the full email address for each team member of any Windows AD group. -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). +### Ensure recipient permissions for event artifacts -## Is this a team subscription, which contains a "@Me" filter clause? +An event email includes any event artifact data, such as a work item. The intended email recipients must have permission to view the event artifacts. Recipients without sufficient permission don't receive the email. The system filters the email recipients to include only members with sufficient permissions. -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. +Determine whether filtering based on permissions is causing the missing email notification by checking the notification delivery logs. For more information, see [How to enable subscription logging for troubleshooting](use-subscription-logging.md). -## Do you have permission to see the event artifact? +### Confirm subscription creator or modifier permissions -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). +Email notifications can stop when permissions change for the subscription creator or the last user to modify the subscription. -## Known issue +When the creator or the last modifying user lose permissions to the project, the system filters notifications for the subscription silently. No emails are delivered. -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. +Check the details for the subscription, and verify the permissions for all users with subscription-level access. -## Contact customer support +## Related content -If you're not able to resolve the issue with the previous steps, consider contacting [customer support](troubleshoot-contact-support.md) +- Contact [customer support](../../user-guide/provide-feedback.md) \ No newline at end of file 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..4a80b64adfd 100644 --- a/docs/organizations/notifications/unsubscribe-default-notification.md +++ b/docs/organizations/notifications/unsubscribe-default-notification.md @@ -1,77 +1,54 @@ ---- -title: View subscribed notifications +--- +title: View Subscribed Notifications titleSuffix: Azure DevOps description: View your notifications and unsubscribe from a default or built-in notification in Azure DevOps. ms.subservice: azure-devops-notifications ms.custom: quarterly-update, engagement-fy23 -ms.topic: conceptual +ms.topic: how-to ms.author: chcomley author: chcomley -ms.date: 01/23/2023 -monikerRange: '<= azure-devops' +ms.date: 05/07/2025 +#customer intent: As a subscriber to Azure DevOps, I want to see my subscribed notifications so I can opt out from notifications and stop receiving emails. --- # View your subscriptions, opt out as needed [!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). - -## View subscriptions - -::: moniker range=">= azure-devops-2019" - -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) - -2. Select **Notifications**. +If you want to stop receiving specific email notifications, you can unsubscribe from the notifications in Azure DevOps. You can opt out of default or built-in subscriptions and unsubscribe from other notifications. For a description of each default subscription, see [Default notifications](oob-built-in-notifications.md). - Your subscribed notifications show the State as **On**. +## Prerequisites - ![Notifications turned On](media/notifications-turned-on.png) +[!INCLUDE [prerequisites-project-member-only](../../includes/prerequisites-project-member-only.md)] - 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 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 +## View subscriptions -::: moniker range="tfs-2018" +To open your personal notifications, select the **User settings** icon :::image type="icon" source="../../media/icons/user-settings-gear.png"::: in Azure DevOps, and then select **Notifications** or **Notification settings**: -1. From the web portal, select your initials or picture, and select **Notification settings** from the drop-down menu. +:::image type="content" source="media/personal/open-user-notifications.png" alt-text="Screenshot that shows how to open your personal notifications page in Azure DevOps."::: - Open personal notification settings +The **User settings > Notifications** page opens: - Your subscribed notifications show the State as **On**. +:::image type="content" source="media/personal/user-notifications-page.png" alt-text="Screenshot of the User settings, Notifications page in Azure DevOps."::: - Personal notification subscriptions +Your subscribed notifications show the **State** toggle in the _On_ position, which is colored blue: - The following image indicates a subscription is a default or out-of-the-box (OOB) subscription: +:::image type="content" source="media/notifications-turned-on.png" alt-text="Screenshot that shows enabled notifications where the State is set to On and the toggle is colored blue."::: - ![OOB notification](media/oob-notification.png) +Azure DevOps shows the globe icon :::image type="icon" source="media/oob-notification.png"::: for default or out-of-the-box (OOB) subscriptions: - You can't modify an OOB subscription, but you can view its definition from its context menu. +:::image type="content" source="media/notifications-default.png" alt-text="Screenshot that shows how the globe icon indicates an OOB or default notification."::: -2. To unsubscribe, slide the state **On/Off** indicator to the *Off* position. +You can't modify an OOB subscription, but you can view its definition from its **More options** menu (**...**). - In the following image, the "Build completes" subscription is turned off. +## Unsubscribe from a notification - Unsubscribe from Build completes subscription +To unsubscribe from a notification, slide the **State** toggle to the _Off_ position. The toggle color changes to white and the entire subscription row is grayed: -::: moniker-end +:::image type="content" source="media/notification-turned-off.png" alt-text="Screenshot that shows a disabled notification where the State is set to Off and the toggle is colored white. The entire subscription row is grayed."::: -## Related articles +## Related content - [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) \ No newline at end of file diff --git a/docs/organizations/notifications/use-subscription-logging.md b/docs/organizations/notifications/use-subscription-logging.md index 1ce9b057ed0..d466ad8217f 100644 --- a/docs/organizations/notifications/use-subscription-logging.md +++ b/docs/organizations/notifications/use-subscription-logging.md @@ -1,73 +1,70 @@ --- -title: How to enable subscription logging +title: Use subscription logging to troubleshoot notifications titleSuffix: Azure DevOps -description: How to use subscription logging to troubleshoot Azure DevOps Services notifications +description: Enable subscription logging and access diagnostic logs to troubleshoot notification issues in Azure DevOps. ms.subservice: azure-devops-notifications ms.reviewer: wismythe ms.author: chcomley author: chcomley -ms.topic: conceptual -ms.date: 01/22/2020 +ms.topic: how-to +ms.date: 07/02/2025 monikerRange: '<= azure-devops' +#customer intent: As a project member, I want to enable subscription logging and access diagnostic logs so that I can troubleshoot notification delivery issues in Azure DevOps. --- - -# How to enable subscription logging for troubleshooting +# Use subscription logging to troubleshoot notifications [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] [!INCLUDE [note-smtp-server](includes/note-smtp-server.md)] - 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. - -## Enabling subscription logging +Subscription logging helps you troubleshoot notification issues by providing diagnostic information from the notifications pipeline. This feature is disabled by default. When enabled, Azure DevOps collects up to 25 logs or one hour's worth of diagnostic data for the subscription, whichever limit is reached first. -> [!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. +## Prerequisites -Complete the following steps to enable subscription logging: +[!INCLUDE [prerequisites-project-member-only](../../includes/prerequisites-project-member-only.md)] -1. Enable diagnostics for your organization by entering the following URL in your browser: +## Enable subscription logging - `https://dev.azure.com/{organization}/_notifications?diagnostics=true` +1. Go to the notifications page with diagnostics enabled by entering this URL in your browser: -2. The option _Enable Diagnostics_ appears in the subscription context menu. - -> [!div class="mx-imgBorder"] ->![Enable subscription logging](media/enable-subscription-logging.png) + `https://dev.azure.com/{Your_Organization}/_notifications?diagnostics=true` -## View subscription diagnostic logs for event matching + Replace `{Your_Organization}` with your organization name (for example, `https://dev.azure.com/contoso/_notifications?diagnostics=true`). -Get all subscription event processing logs by entering the following URL in your browser: +2. On the notifications page, locate the subscription you want to debug and select its context menu (three dots). -`https://dev.azure.com/{organization}/_apis/notification/DiagnosticLogs/{event ID}/entries?startTime={date}&endTime={date}` +3. Select **Enable Diagnostics** from the menu to start collecting logs for that subscription. -* _organization_ is your organization (for example, dev.azure.com/fabrikam-fiber) -* _date_ is a date time specification (for example, **2018-06-29** or **2018-06-29 02:00**) -* _event ID_ is **915f48f2-1b64-40d9-a43f-fe2528b4f296** for work item events, or -* _event ID_ is **9a688110-9e33-4cdc-affd-75d16303e7f1** for Git events, or -* _event ID_ is **a4804dcf-4bb6-4109-b61c-e59c2e8a9ff7** for any other event type - -The result is JSON-formatted logging information. - -## View subscription diagnostic logs for notification delivery - -Retrieve all notification delivery logs in a given time frame by entering the URL in your browser. +> [!div class="mx-imgBorder"] +>![Screenshot shows enabled subscription logging.](media/enable-subscription-logging.png) -`https://dev.azure.com/{organization}/_apis/notification/DiagnosticLogs/{event ID}/entries?startTime={date}&endTime={date}` +## View subscription diagnostic logs -* _organization_ is your organization (for example, dev.azure.com/fabrikam-fiber) -* _date_ is a date time specification (for example, **2018-06-29** or **2018-06-29 02:00**) -* _event ID_ is **631f49b3-46e1-42ec-8fff-081bd176c18a** for work item events, or -* _event ID_ is **8833fc71-42ca-441b-ab12-25314877772d** for Git events, or -* _event ID_ is **a96d6177-beef-477a-a2ee-2c31433214d0** for any other event type +Access subscription diagnostic logs directly using API calls. Enter the following URL in your browser: -The result is JSON-formatted logging information. +`https://dev.azure.com/{Your_Organization}/_apis/notification/DiagnosticLogs/{eventID}/entries?startTime={date}&endTime={date}` +**Parameters:** +* `{Your_Organization}` - Your organization name (for example, `contoso`) +* `{date}` - Date and time in format `YYYY-MM-DD` or `YYYY-MM-DD HH:MM` (for example, `2025-07-02` or `2025-07-02 14:30`) +* `{eventID}` - Use the appropriate event ID based on the type of logs you need: +**Event matching logs:** +* `915f48f2-1b64-40d9-a43f-fe2528b4f296` for work item events +* `9a688110-9e33-4cdc-affd-75d16303e7f1` for Git events +* `a4804dcf-4bb6-4109-b61c-e59c2e8a9ff7` for other event types +**Notification delivery logs:** +* `631f49b3-46e1-42ec-8fff-081bd176c18a` for work item events +* `8833fc71-42ca-441b-ab12-25314877772d` for Git events +* `a96d6177-beef-477a-a2ee-2c31433214d0` for other event types +Returns JSON-formatted diagnostic 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..ded051565c8 100644 --- a/docs/organizations/projects/delete-project.md +++ b/docs/organizations/projects/delete-project.md @@ -1,49 +1,69 @@ --- -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. +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 +ms.custom: + - engagement-fy23 + - sfi-image-nochange --- # 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 +73,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 +105,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 +160,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 +167,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/te-home-page-git-repo-visual-studio-2022.png b/docs/organizations/projects/media/te-home-page-git-repo-visual-studio-2022.png new file mode 100644 index 00000000000..ac8a697b631 Binary files /dev/null and b/docs/organizations/projects/media/te-home-page-git-repo-visual-studio-2022.png differ diff --git a/docs/organizations/projects/media/te-home-page-git-repo.png b/docs/organizations/projects/media/te-home-page-git-repo.png index 7f5da506933..6c25bc4447c 100644 Binary files a/docs/organizations/projects/media/te-home-page-git-repo.png and b/docs/organizations/projects/media/te-home-page-git-repo.png differ diff --git a/docs/organizations/projects/media/te-home-page-tfvc-repo.png b/docs/organizations/projects/media/te-home-page-tfvc-repo.png index 7b39a4c8a61..d5fbd0a8835 100644 Binary files a/docs/organizations/projects/media/te-home-page-tfvc-repo.png and b/docs/organizations/projects/media/te-home-page-tfvc-repo.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..91138174f57 100644 --- a/docs/organizations/security/about-security-identity.md +++ b/docs/organizations/security/about-security-identity.md @@ -1,5 +1,5 @@ --- -title: About security, authentication, authorization, and security policies +title: About authentication, authorization, and security policies titleSuffix: Azure DevOps description: Learn how Azure DevOps manages security through authentication, authorization, and policies ms.subservice: azure-devops-security @@ -7,16 +7,16 @@ ms.author: chcomley author: chcomley ms.topic: overview monikerRange: '<= azure-devops' -ms.date: 03/23/2023 +ms.date: 06/16/2025 --- -# About security, authentication, and authorization +# About authentication, authorization, and security policies [!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 uses a combination of security concepts to ensure that only authorized users can access its features, functions, and data. Access gets determined by two key processes: authentication, which verifies a user's credentials, and authorization, which grants permissions based on account entitlements. Together, these processes control what each user can do within Azure DevOps. -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 expands on [Get started with permissions, access, and security groups](../security/about-permissions.md) and helps administrators understand the different account types, authentication and authorization methods, and security policies available to protect Azure DevOps environments. ::: moniker range="azure-devops" @@ -30,13 +30,13 @@ This article builds on the information provided in [Get started with permissions - Service principals or managed identities - Job agents - **Authentication** - User credentials - Windows authentication - Two-factor authentication (2FA) - SSH key authentication - - Personal access tokens + - Microfost Entra token + - Personal access token - Oauth configuration - Active Directory authentication library :::column-end::: @@ -48,7 +48,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,150 +99,123 @@ 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 supports software development from planning to deployment. Each platform uses 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 projects are safe, available, secure, and private, see the [Azure DevOps 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 non-Microsoft 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. +- **Third party accounts**: Accounts that require access to support Web hooks, service connections, or other non-Microsoft 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 non-Microsoft 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. +- **Third party accounts**: Accounts that require access to support Web hooks, service connections, or other non-Microsoft 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) -- 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). - -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). - -### Authentication methods, integrating with other services and apps +Authentication verifies a user's identity based on the credentials provided during sign-in to Azure DevOps. Azure DevOps integrates with several identity systems to manage authentication: -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. +- **Microsoft Entra ID**: Recommended for organizations managing a large group of users. Provides robust, cloud-based authentication and user management. +- **Microsoft account (MSA)**: Suitable for smaller user bases accessing Azure DevOps organizations. Supports cloud authentication. +- **Active Directory (AD)**: Recommended for on-premises deployments with many users, using your existing AD infrastructure. -- [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/) +Microsoft Entra ID and Microsoft accounts both support cloud authentication. For more information, see [About accessing Azure DevOps with Microsoft Entra ID](../accounts/access-with-azure-ad.md). -- [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. +For on-premises environments, use Active Directory to efficiently manage user access. Learn more in [Set up groups for use in on-premises deployments](/azure/devops/server/admin/setup-ad-groups). -- [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. +### Authenticate programmatically -- [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. +Access your Azure DevOps organization programmatically without repeatedly entering your username and password by choosing one of the available [authentication methods](../../integrate/get-started/authentication/authentication-guidance.md). Use the following methods to automate workflows, integrate with REST APIs, or build custom applications: -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. +- Use [OAuth](../../integrate/get-started/authentication/oauth.md) to build applications that perform actions on behalf of users. Users must consent to the app. For new apps, use [Microsoft Entra OAuth](../../integrate/get-started/authentication/entra-oauth.md). +- Use [service principals or managed identities](../../integrate/get-started/authentication/service-principal-managed-identity.md) to automate workflows or build tools that regularly access organization resources. Issue Microsoft Entra tokens on behalf of the application itself. +- Use [Microsoft Entra ID](../../integrate/get-started/authentication/entra.md) for secure, cloud-based authentication and user management. +- Use [personal access tokens (PATs)](../accounts/use-personal-access-tokens-to-authenticate.md) for ad-hoc requests or early prototyping. Avoid PATs for long-term app development, as they're more susceptible to leaks and misuse. -For more information about how we store your credentials, see [Credential storage for Azure DevOps](credential-storage.md). +> [!TIP] +> Always [store credentials securely](credential-storage.md) and follow best practices for managing authentication methods. -For more information about how to choose the right authentication mechanism, see [Guidance for authentication](../../integrate/get-started/authentication/authentication-guidance.md). - - +By default, your organization allows access for all authentication methods. Organization admins can [restrict access to these authentication methods by disabling security policies](../accounts/change-application-access-policies.md). Tenant admins can further [reduce PAT risk by restricting the ways in which they can be created](../accounts/manage-pats-with-policies-for-administrators.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 determines whether an authenticated identity has the required permissions to access a specific service, feature, function, object, or method in Azure DevOps. Authorization checks always occur after successful authentication—if authentication fails, authorization is never evaluated. Even after authentication, users or groups might be denied access to certain actions if they lack the necessary permissions. -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). +Azure DevOps manages authorization through permissions assigned directly to users or inherited through security groups or roles. Access levels and feature flags can further control access to specific features. To learn more 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 define user access levels for specific actions on Azure DevOps resources. + +- Each resource family, for example, work items or Git repositories, has its own unique namespace. +- Within each namespace, there can be multiple access control lists (ACLs). + - Each ACL contains a token, an inherit flag, and one or more access control entries (ACEs). + - Each ACE specifies an identity descriptor, a bitmask for allowed permissions, and a bitmask for denied permissions. -For more information, see [Security namespaces and permission reference](namespace-reference.md). +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: - -### General +To secure your organization and code, organization-level ([Project Collection Administrator](look-up-project-collection-administrators.md)) or tenant-level ([Azure DevOps Administrator](/entra/identity/role-based-access-control/permissions-reference#azure-devops-administrator)) admins can enable or disable various security policies, depending on the policy scope. Key policies to consider include: -- **Privacy policy URL**: Specifies a URL that links to your custom document that describes how you handle both internal and external guest data privacy. For more information, see [Add a privacy policy URL for your organization](../accounts/add-privacy-policy-url.md). +- [Specify a privacy policy URL](../accounts/add-privacy-policy-url.md) to describe how you handle internal and external guest data privacy. +- Decide whether users in your organization are [allowed to create public projects](../projects/make-project-public.md). -### Application connection and security policies +If your organization is connected to Microsoft Entra ID, you have access to the following other security features: -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. +- [Restrict organization creation to specific users](../accounts/azure-ad-tenant-policy-restrict-org-creation.md). +- [Invite external guests to the organization](../accounts/add-external-user.md). +- [Allow team and project administrators to invite new users](restrict-invitations.md). +- [Enable Conditional Access policy (CAP) validation](../accounts/change-application-access-policies.md#cap-support-on-azure-devops). +- Track [auditing events and streams](../audit/azure-devops-auditing.md) in your organization. -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). -- **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). +Review and configure these policies to strengthen your organization's security posture and ensure compliance with your data privacy and access requirements. -### 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). - - + ### 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 limit access for specific users—such as Stakeholders, Microsoft Entra guest users, or members of a particular security group—enable the **Limit user visibility and collaboration to specific projects** preview feature for your organization. When this feature is enabled, any user or group added to the **Project-Scoped Users** group is restricted in the following ways: +- Access is limited to the **Overview** and **Projects** pages within **Organization settings**. +- Users can only connect to and view projects they're [explicitly added to](add-users-team-project.md). +- Users can only select user and group identities that are explicitly added to the same project. -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 +230,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 +245,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 +261,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..67f9d8a2e47 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,166 @@ --- -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 +ms.custom: sfi-image-nochange --- -# 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 +171,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..4c9b4b0fbdd 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 @@ -3,40 +3,33 @@ title: Add or remove users or groups titleSuffix: Azure DevOps description: How-to guide to add or remove users or groups to security groups and manage security groups 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: 04/04/2022 +ms.date: 10/20/2023 +ms.custom: + - security-refresh + - sfi-image-nochange --- - -# 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 +43,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 +166,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 +204,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 +224,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 +270,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 +286,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 +317,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 +338,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 +362,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 +371,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 +380,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 +396,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..41b3e449d2b 100644 --- a/docs/organizations/security/add-users-team-project.md +++ b/docs/organizations/security/add-users-team-project.md @@ -1,65 +1,56 @@ --- 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 +ms.custom: sfi-image-nochange --- - # 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 +71,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 +92,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 +118,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 +141,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 +160,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 +200,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 +209,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 +239,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 +276,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 +298,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 +312,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 +324,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 +336,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 +345,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 +397,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 +409,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 +441,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 +452,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 +608,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 +639,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 +652,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 +667,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..4ce8dee25a1 100644 --- a/docs/organizations/security/allow-list-ip-url.md +++ b/docs/organizations/security/allow-list-ip-url.md @@ -1,42 +1,49 @@ --- -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: 07/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. + +**Required ports:** +- **Port 443 (HTTPS)**: Required for all Azure DevOps web access, REST API calls, and most service connections +- **Port 22 (SSH)**: Required only for Git operations using SSH protocol + +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 on **port 443 (HTTPS)**, 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 +53,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 +69,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 +79,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 +92,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 on **port 443 (HTTPS)**, 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 @@ -123,7 +144,7 @@ For more information, see [Worldwide endpoints](/microsoft-365/enterprise/urls-a ### Azure DevOps ExpressRoute connections -If your organization uses ExpressRoute, ensure the following IP addresses are allowed for both outbound and inbound connections. +If your organization uses ExpressRoute, ensure the following IP addresses are allowed for both outbound and inbound connections on **port 443 (HTTPS)**. #### [IP V4 ranges](#tab/IP-V4) @@ -140,6 +161,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 +196,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 ``` --- @@ -165,9 +222,13 @@ For more information about Azure DevOps and ExpressRoute, see [ExpressRoute for ## Allowed Domain URLs -Network connection issues could occur because of your security appliances, which may be blocking connections - Visual Studio uses TLS 1.2 and above. When you're using [NuGet](#nuget-connections) or connecting from Visual Studio 2015 and later, update the security appliances to support TLS 1.2 and above for the following connections. +Network connection issues could occur because of your security appliances, which might be blocking connections - Visual Studio uses TLS 1.2 and above. When you're using [NuGet](#nuget-connections) or connecting from Visual Studio 2015 and later, update the security appliances to support TLS 1.2 and above for the following connections. + +**Port requirements for domain URLs:** +- **Port 443 (HTTPS)**: Required for all domain URLs listed in this article +- **Port 22 (SSH)**: Required only for SSH Git connections (see [SSH connections](#ssh-connections) section) -To ensure your organization works with any existing firewall or IP restrictions, ensure that `dev.azure.com` and `*.dev.azure.com` are open. +To ensure your organization works with any existing firewall or IP restrictions, ensure that `dev.azure.com` and `*.dev.azure.com` are open on **port 443**. The following section includes the most common domain URLs to support sign in and licensing connections. @@ -177,7 +238,7 @@ https://dev.azure.com https://*.dev.azure.com https://aex.dev.azure.com https://aexprodea1.vsaex.visualstudio.com -https://*vstmrblob.vsassets.io +https://*.vstmrblob.vsassets.io https://amp.azure.net https://app.vssps.dev.azure.com https://app.vssps.visualstudio.com @@ -195,7 +256,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,10 +263,13 @@ https://{organization_name}.vstmr.visualstudio.com https://{organization_name}.pkgs.visualstudio.com https://{organization_name}.vssps.visualstudio.com +Azure DevOps uses the following URL to provide the agent software for download for self-hosted agents. +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 -https://*gallerycdn.vsassets.io +https://*.gallerycdn.vsassets.io https://aadcdn.msauth.net https://aadcdn.msftauth.net https://amcdn.msftauth.net @@ -214,15 +277,15 @@ 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 https://login.live.com ``` -The following URL is required if you're migrating from Azure DevOps server to the cloud service using our data migration tool. +The following URL is required if you're migrating from Azure DevOps Server to the cloud service using our data migration tool. ``` https://dataimport.dev.azure.com ``` @@ -237,19 +300,22 @@ https://dataimport.dev.azure.com We recommend you open port `443` to all traffic on the following IP addresses and domains. We also recommend you open port `22` to a smaller subset of targeted IP addresses. -|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://amp.azure.net | Needed for deploying to Azure app service | -|https://go.microsoft.com | Accesses go links | +**Port configuration summary:** +- **Port 443 (HTTPS)**: Open to ALL domain URLs and IP addresses listed in this article +- **Port 22 (SSH)**: Open only to SSH-specific hosts listed in the [SSH connections](#ssh-connections) section + +|More domain URLs |Descriptions |Required Port | +|---------|---------|---------| +|https://login.microsoftonline.com |Authentication and sign-in related |443 | +|https://*.vssps.visualstudio.com |Authentication and sign-in related |443 | +|https://*.gallerycdn.vsassets.io |Hosts Azure DevOps extensions |443 | +|https://*.vstmrblob.vsassets.io | Hosts Azure DevOps TCM log data |443 | +|https://cdn.vsassets.io | Hosts Azure DevOps Content Delivery Networks (CDNs) content |443 | +|https://static2.sharepointonline.com | Hosts some resources that Azure DevOps uses in "office fabric" UI kit for fonts, and so on |443 | +|https://vsrm.dev.azure.com | Hosts releases |443 | +|https://download.agent.dev.azure.com | Required to set up self-hosted agent in machines within your network |443 | +|https://amp.azure.net | Needed for deploying to Azure app service |443 | +|https://go.microsoft.com | Accesses go links |443 | ### Azure Artifacts @@ -258,6 +324,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 +334,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] @@ -276,7 +343,7 @@ https://nuget.org ### SSH connections -If you need to connect to Git repositories on Azure DevOps with SSH, allow requests to port 22 for the following hosts: +If you need to connect to Git repositories on Azure DevOps with SSH, allow requests to **port 22** for the following hosts: ```SSHDomainHosts @@ -284,22 +351,35 @@ ssh.dev.azure.com vs-ssh.visualstudio.com ``` -Also allow IP addresses in the "name": "AzureDevOps" section of [this downloadable file](https://www.microsoft.com/download/details.aspx?id=56519) (updated weekly) named: **Azure IP ranges and Service Tags - Public Cloud** +Also allow **port 22** for IP addresses in the "name": "AzureDevOps" section of [this downloadable file](https://www.microsoft.com/download/details.aspx?id=56519) (updated weekly) named: **Azure IP ranges and Service Tags - Public Cloud** ### 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 was retired](https://devblogs.microsoft.com/devops/important-switching-cdn-providers/), which required a new domain URL to be allow-listed in firewall rules for agent software download. +> The new domain to allowlist 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 recommended making 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..12245ec167b 100644 --- a/docs/organizations/security/data-protection.md +++ b/docs/organizations/security/data-protection.md @@ -2,96 +2,97 @@ title: Data protection overview titleSuffix: Azure DevOps Services description: Learn how Microsoft helps protect your projects and data in Azure DevOps. -ms.custom: freshness-fy22 ms.topic: article ms.subservice: azure-devops-security ms.author: chcomley author: chcomley ms.reviewer: jominana -ms.date: 05/17/2023 +ms.date: 06/20/2025 monikerRange: 'azure-devops' +ms.custom: + - freshness-fy22 + - sfi-ropc-nochange --- - # 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 +100,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 27001:2022 - 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..08e98ec68bd 100644 --- a/docs/organizations/security/includes/note-group-rules.md +++ b/docs/organizations/security/includes/note-group-rules.md @@ -3,10 +3,12 @@ ms.subservice: azure-devops-security ms.author: chcomley author: chcomley ms.topic: include -ms.date: 02/24/2023 +ms.date: 07/02/2025 --- > [!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). +> - Group rules for licensing currently don't apply to service principals and managed identities. To assign an access level to a service principal or managed identity, assign it directly rather than through group membership. 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/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..9ccaf165fc7 100644 --- a/docs/organizations/security/includes/project-level-permissions.md +++ b/docs/organizations/security/includes/project-level-permissions.md @@ -3,84 +3,66 @@ ms.subservice: azure-devops-security ms.author: chcomley author: chcomley ms.topic: include -ms.date: 02/28/2022 +ms.date: 05/05/2025 --- -::: 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 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 +The following table lists the permissions assigned at the project-level. All these permissions are granted to members of the **Project Administrators** group, except for the **Delete shared Analytics views** and **Edit shared Analytics views** permissions. For a description of each permission, see [Permissions and groups reference, Groups](../permissions.md#project-level-permissions). -::: 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" > [!NOTE] -> Permissions associated with Analytics requires that the Inherited process model is selected for an on-premises project collection. -::: moniker-end +> Permissions associated with Analytics require that the Inherited process model is selected for an on-premises project collection. :::row::: :::column span=""::: - **General** + + **General** + ::: moniker range="azure-devops" + - Delete team project - Edit project-level information - Manage project properties - Rename team project - Suppress notifications for work item updates - Update project visibility - - View project-level information + - 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..1fbea07b601 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: 06/16/2025 # linkListType: architecture | concept | deploy | download | get-started | how-to-guide | learn | overview | quickstart | reference | tutorial | video | whats-new @@ -25,6 +25,10 @@ landingContent: links: - text: About permissions, access, and security groups url: about-permissions.md + - text: About authentication, authorization, & security policies + url: about-security-identity.md + - text: Security checklist + url: security-overview.md - linkListType: quickstart links: - text: View permissions @@ -37,7 +41,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: @@ -45,38 +49,26 @@ landingContent: url: access-levels.md - text: Stakeholder access quick reference url: stakeholder-access.md + - text: Replace PATs with Microsoft Entra tokens + url: ../../integrate/get-started/authentication/entra.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,28 +80,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 - linkLists: - - linkListType: concept - links: - - text: About security, authentication, & authorization - url: about-security-identity.md - - text: Authentication guidance - url: ../../integrate/get-started/authentication/authentication-guidance.md?toc=/azure/devops/organizations/security/toc.json - - linkListType: how-to-guide - links: - - text: Use personal access tokens (PATs) - url: ../accounts/use-personal-access-tokens-to-authenticate.md?toc=/azure/devops/organizations/security/toc.json - - text: Manage PATs via API - url: ../accounts/manage-personal-access-tokens-via-api.md?toc=/azure/devops/organizations/security/toc.json - - text: Revoke user PATs - url: ../accounts/admin-revoke-user-pats.md?toc=/azure/devops/organizations/security/toc.json - - text: Authorize access to REST APIs with OAuth 2.0 - url: ../../integrate/get-started/authentication/oauth.md?toc=/azure/devops/organizations/security/toc.json - - title: Secure projects + - title: Secure organizations and projects linkLists: - linkListType: overview links: @@ -117,6 +91,10 @@ landingContent: url: restrict-access.md - linkListType: quickstart links: + - text: Look up a project collection administrator + url: look-up-project-collection-administrators.md + - text: Change permissions at the organization or collection-level + url: change-organization-collection-level-permissions.md - text: Look up a project administrator url: look-up-project-administrators.md - text: Change project-level permissions @@ -129,20 +107,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-azure-devops-administrator.md b/docs/organizations/security/look-up-azure-devops-administrator.md new file mode 100644 index 00000000000..4f90a4f2326 --- /dev/null +++ b/docs/organizations/security/look-up-azure-devops-administrator.md @@ -0,0 +1,32 @@ +--- +title: Look up an Azure DevOps Administrator +titleSuffix: Azure DevOps +description: Learn how to identify members of the Azure DevOps Administrators group on Microsoft Entra. +ms.subservice: azure-devops-security +ms.custom: security-refresh +ms.author: chcomley +author: chcomley +ms.topic: how-to +monikerRange: '<= azure-devops' +ms.date: 07/12/2024 +--- + +# Look up an Azure DevOps Administrator + +[!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] + +The [**Azure DevOps Administrator**](/entra/identity/role-based-access-control/permissions-reference#azure-devops-administrator) role is managed through Microsoft Entra ID and used for tenant-wide administration: +* **Claim ownership of [orphaned Azure DevOps organizations](../accounts/resolve-orphaned-organization.md)**. +* **[Configure tenant-level policies](../accounts/change-application-access-policies.md)** on the "Microsoft Entra" page in Organization Settings. If you're not an Azure DevOps Administrator, the tenant-level policies on this page won't be visible to you. + +Being a [Project Collection Administrator](look-up-project-collection-administrators.md) isn't required for the Azure DevOps Administrator role. + +## Look up your Azure DevOps Administrators + +1. Sign in to the [Azure portal](https://portal.azure.com). + +2. Select "**Microsoft Entra ID**" and find "**Roles and administrators**" on the right sidebar. + +3. Search for the "Azure DevOps Administrator" group to see all current assignments to the group. + +2. If you want to join the role, contact your tenant administrator to learn how to be assigned this role in your company. 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..11b4e417ee6 100644 --- a/docs/organizations/security/look-up-project-administrators.md +++ b/docs/organizations/security/look-up-project-administrators.md @@ -1,43 +1,42 @@ --- 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 +ms.custom: + - security-refresh + - sfi-image-nochange --- # 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 +46,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..3ff75e9e3f7 100644 --- a/docs/organizations/security/look-up-project-collection-administrators.md +++ b/docs/organizations/security/look-up-project-collection-administrators.md @@ -1,115 +1,85 @@ --- 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 +ms.custom: + - security-refresh + - sfi-image-nochange --- # 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 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 -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 - -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). +Organization owners are automatically members of this group. 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). -## Prerequisites +For more information, see [Get started with permissions and security groups](about-permissions.md). -* 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. - +## Prerequisites -::: 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 +90,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..07eb7cafdc4 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: 06/23/2025 --- # 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,10 +89,10 @@ 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` + **Example**: `$/Shared/00001111-aaaa-2222-bbbb-3333cccc4444`
      **ID:** `d34d3680-dfe5-4cc6-a949-7d9c68f73cba` :::column-end::: @@ -125,9 +124,9 @@ 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` + **Example**: `00001111-aaaa-2222-bbbb-3333cccc4444/12`
      **ID:** `33344d9c-fc72-4d6f-aba5-fa317101a7e9` :::column-end::: @@ -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,15 +167,21 @@ 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).
      + **Token format for Team Dashboard permissions**: `$/PROJECT_ID/Team_ID/Dashboard_ID` + **Example**: `$/66667777-aaaa-8888-bbbb-9999cccc0000/00001111-aaaa-2222-bbbb-3333cccc4444/55556666-ffff-7777-aaaa-8888bbbb9999` +

      + **Token format for Project Dashboard permissions**: `$/PROJECT_ID/00001111-aaaa-2222-bbbb-3333cccc4444/Dashboard_ID` + **Example**: `$/66667777-aaaa-8888-bbbb-9999cccc0000/00001111-aaaa-2222-bbbb-3333cccc4444/55556666-ffff-7777-aaaa-8888bbbb9999` +

      **ID:** `8adf73b7-389a-4276-b638-fe1653f7efc7` :::column-end::: :::row-end::: --- :::row::: :::column span="1"::: - GitRepositories + Git Repositories :::column-end::: :::column span="1"::: `Administer` @@ -196,15 +202,18 @@ 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 +241,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 +258,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 +283,11 @@ 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). +
      + **Token Format**: `Plan/PROJECT_ID/DeliveryPlan_ID` +

      + **Example**: `Plan/00001111-aaaa-2222-bbbb-3333cccc4444/55556666-ffff-7777-aaaa-8888bbbb9999`
      **ID:** `bed337f8-e5f3-4fb9-80da-81e17d06e7a8` :::column-end::: @@ -304,11 +317,11 @@ The following table describes the namespaces that manage object-level permission [Manages release definition permissions at the project and object-level](permissions.md#release-management).
      **Token format for project-level permissions**: `PROJECT_ID` - **Example**: `xxxxxxxx-a1de-4bc8-b751-188eea17c3ba` + **Example**: `00001111-aaaa-2222-bbbb-3333cccc4444` If you need to update permissions for a particular release definition ID, for example, 12, security token for that release definition looks as follows:
      **Token format for specific release definition permissions**: `PROJECT_ID/12` - **Example**: `xxxxxxxx-a1de-4bc8-b751-188eea17c3ba/12` + **Example**: `00001111-aaaa-2222-bbbb-3333cccc4444/12` If the release definition ID lives in a folder, then the security tokens look as follows: **Token format**: `PROJECT_ID/{folderName}/12` For stages, tokens look like: `PROJECT_ID/{folderName}/{DefinitionId}/Environment/{EnvironmentId}`. @@ -330,17 +343,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 +401,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. @@ -396,9 +409,9 @@ The following table describes the namespaces that manage project-level permissio Assume you have a project named `Test Project 1`. You can get the project ID for this project by using the [`az devops project show` command](../projects/create-project.md). `az devops project show --project "Test Project 1"` - The command returns a project-id, for example, `xxxxxxxx-a1de-4bc8-b751-188eea17c3ba`. + The command returns a project-id, for example, `00001111-aaaa-2222-bbbb-3333cccc4444`. 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/00001111-aaaa-2222-bbbb-3333cccc4444'`
      **ID:** `52d39943-cb85-4d7f-8fa8-c6baac873819` :::column-end::: @@ -406,7 +419,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,10 +428,10 @@ 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` + **Example**: `/00001111-aaaa-2222-bbbb-3333cccc4444`
      **ID:** `bb50f182-8e5e-40b8-bc21-e8752a1e7ae2` :::column-end::: @@ -444,7 +457,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 +468,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 +556,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 +622,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 +664,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 +687,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 +777,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 +799,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 +809,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 +844,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 @@ -850,7 +860,7 @@ The following table describes the security namespaces and permissions that aren' Manages permissions to read, administer permissions, and execute queries against the Analytics service.
      **Token format for project-level permissions**: `$/PROJECT_ID` - **Example**: `$/xxxxxxxx-a1de-4bc8-b751-188eea17c3ba` + **Example**: `$/00001111-aaaa-2222-bbbb-3333cccc4444`
      **ID:** `58450c49-b02d-465a-ab12-59ae512d6531` :::column-end::: @@ -887,7 +897,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::: @@ -1018,9 +1028,9 @@ The following table describes the security namespaces and permissions that aren' Manages permissions to read, write, and delete user account identity information; manage group membership and create and restore identity scopes. The `ManageMembership` permission is automatically granted to members of the Project Administrators and Project Collection Administrators groups. **Token format for project-level permissions**: `PROJECT_ID` - **Example**: `xxxxxxxx-a1de-4bc8-b751-188eea17c3ba` - To modify group level permissions for Group Origin ID [2b087996-2e64-4cc1-a1dc-1ccd5e7eb95b]: - **Token**: `xxxxxxxx-a1de-4bc8-b751-188eea17c3ba\2b087996-2e64-4cc1-a1dc-1ccd5e7eb95b` + **Example**: `00001111-aaaa-2222-bbbb-3333cccc4444` + To modify group level permissions for Group Origin ID [11112222-bbbb-3333-cccc-4444dddd5555]: + **Token**: `00001111-aaaa-2222-bbbb-3333cccc4444\11112222-bbbb-3333-cccc-4444dddd5555`
      **ID:** `5a27515b-ccd7-42c9-84f1-54c998f03866` :::column-end::: @@ -1071,7 +1081,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::: @@ -1124,7 +1134,7 @@ The following table describes the security namespaces and permissions that aren' :::column span="2"::: Manages access to Release Management user interface elements.
      - **ID:** `7c7d32f7-0e86-4cd6-892e-b35dbba870bd ` + **ID:** `7c7d32f7-0e86-4cd6-892e-b35dbba870bd` :::column-end::: :::row-end::: --- @@ -1171,7 +1181,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 +1214,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 +1224,7 @@ The following table describes the security namespaces and permissions that aren' :::row-end::: --- - - + ## Deprecated and read-only namespaces @@ -1257,9 +1266,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..4e8cd02bf3a --- /dev/null +++ b/docs/organizations/security/security-overview.md @@ -0,0 +1,197 @@ +--- +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: 05/28/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. + +## Protect your network and data + +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 and data protection 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](allow-list-ip-url.md):** Restrict access to specific IP addresses to allow traffic only from trusted sources, reducing the attack surface. If your organization is secured with a firewall or proxy server, add IPs and URLs to the allowlist. +- **[Use data encryption](data-protection.md):** Protect your data by using encryption, backup, and recovery strategies. Always encrypt data in transit and at rest. Secure communication channels using protocols like HTTPS. Learn more about [Azure Encryption](/azure/security/fundamentals/encryption-overview). +- **[Validate certificates](/azure/security/fundamentals/azure-ca-details?tabs=root-and-subordinate-cas-list):** Ensure certificates are valid and issued by trusted authorities when establishing connections. +- **[Implement Web Application Firewalls (WAFs)](/azure/web-application-firewall/):** Filter, monitor, and block malicious web-based traffic with WAFs for an extra layer of protection against common attacks. +- **[Network security groups (NSGs) overview](/azure/virtual-network/network-security-groups-overview):** Use NSGs to control inbound and outbound traffic to Azure resources, ensuring only authorized traffic is allowed. +- **[Use Azure Firewall](/azure/firewall/overview):** Deploy Azure Firewall to provide a centralized network security policy across multiple Azure subscriptions and virtual networks. +- **[Monitor network traffic with Azure Network Watcher](/azure/network-watcher/network-watcher-monitoring-overview):** Use Azure Network Watcher to monitor and diagnose network issues, ensuring the security and performance of your network. +- **[Implement DDoS protection with Azure DDoS Protection](/azure/ddos-protection/ddos-protection-overview):** Enable Azure DDoS Protection to safeguard your applications from distributed denial-of-service (DDoS) attacks. + +For more information, see [Application management best practices](/azure/active-directory/manage-apps/application-management-fundamentals). + +## Implement Zero Trust + +Adopt [Zero Trust](/azure/security/fundamentals/zero-trust) principles across your DevOps processes to make sure 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. + +- 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) +- 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). + +## Comply with industry standards + +Ensure your Azure DevOps environment complies with industry standards and regulations that 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 compliance policies:** Implement [branch policies](../../repos/git/branch-policies.md) and [compliance policies for your pipelines](/azure/governance/policy/tutorials/policy-devops-pipelines). +- **Onboard to Component Governance for CI/CDs**, which offers the following benefits: + - 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. + +## Control and restrict access + +Review through all the security policies available to administrators to restrict and control who has access to the organization. Maintain control of the organization by preventing unnecessary project creation. + +- **Disable *“Allow public projects”*:** Disable the option to [create public projects](../projects/make-project-public.md). 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. +- **[Restrict unnecessary authentication mechanisms](../accounts/change-application-access-policies.md)** and limit who has access to allowed authentication. +- **Limit access with Conditional Access Policies**: Protect your organization by [defining Conditional Access policies (CAPs)](/entra/identity/conditional-access/overview) on Microsoft Entra that react to sign-in events and request other actions before a user is granted access. + - Turn on the organization policy to [enable IP CAP validation on non-interactive flows](../accounts/change-application-access-policies.md#cap-support-on-azure-devops). + - Add an extra layer of security by [enabling Microsoft Entra multifactor authentication](/entra/identity/authentication/tutorial-enable-azure-mfa) after sign-in. + +### Manage external guests + +External guest access can introduce potential security risks if not managed properly. 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. + - [Disable "External guest access" organization policy](../accounts/add-external-user.md) on Azure DevOps. +- **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). + +### Remove unnecessary users + +[Removing inactive or unauthorized users from your organization](../accounts/delete-organization-users.md) helps maintain a secure environment and reduces the risk of potential security breaches. + +- **Directly remove inactive Microsoft account users (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. +- **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. You may continue querying work item history using their Azure DevOps user ID. +- **[Revoke user PATs for administrators](../accounts/admin-revoke-user-pats.md):** Ensure secure management of these critical authentication tokens by regularly reviewing and revoking any existing user PATs. +- **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 permissions + +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](#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. + +Learn more about permissions: +- [Permissions and role lookup guide](permissions-lookup-guide.md) +- [Set individual permissions](/azure/devops/organizations/security/request-changes-permissions) + +To ensure secure and efficient management of permissions, properly scope [permissions](permissions.md) 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 [permissions inheritance](about-permissions.md#permission-inheritance) and prevent 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. +- **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](/azure/governance/policy/overview) 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. +- **[Implement Azure role-based control (ABAC)](/azure/role-based-access-control/conditions-overview):** Use ABAC with properly tagged resources to limit unauthorized access. This action ensures that access permissions get granted based on specific attributes, enhancing security by preventing unauthorized resource creation and access. +- **Use security groups:** Use [security groups](add-manage-security-groups.md) 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](../accounts/access-with-azure-ad.md), Active Directory, or Windows security groups when you're managing lots of users. + - Reduce the risk of leaking sensitive information and deploying insecure code by [limiting access to projects and repositories](restrict-access.md) to built-in or custom security groups. + - 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. + - Implement [just-in-time access](../accounts/manage-azure-active-directory-groups.md#configure-just-in-time-access-for-admin-groups) with a Microsoft Entra [Privileged Identity Management (PIM) group](/azure/active-directory/privileged-identity-management/concept-pim-for-groups). Grant elevated permissions only when needed, reducing the risk associated with permanent access. + +## Ditch service accounts + +Historically, service accounts were used with [personal access tokens (PATs)](../accounts/use-personal-access-tokens-to-authenticate.md) to build tools that run automated processes and services. As a result, they often have elevated permissions. Before choosing to continue building with a service account, explore if it's still the right authentication approach for you. + +- **Replace your PATs with Microsoft Entra tokens:** [Microsoft Entra tokens are short-lived (one-hour) tokens](../../integrate/get-started/authentication/entra.md) that can be used in place of most PATs. PATs are popular due to their ease of use, but they're also a popular vector of attack due to the ease in which they're leaked. +- Read up on all the [authentication mechanisms available](../../integrate/get-started/authentication/authentication-guidance.md) before choosing one. +- **Use service principals instead:** [Service principals](../../integrate/get-started/authentication/service-principal-managed-identity.md) represent a Microsoft Entra application's identity and have their own permissions that define what the application can do in a given tenant. Service principals are the recommended choice to manage the permissions needed by the app. Replace any service accounts' PATs with Microsoft Entra tokens acquired for the service principal. + - Take it one step further by authenticating using a managed identity if you're building on top of Azure resources. Managed identities take care of all credential management for you. +- **Use service connections:** Service connections allow you to use service principals inside a pipeline. 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. + - Authenticate with Azure resources using [workload identity federation](../../pipelines/library/connect-to-azure.md#create-an-azure-resource-manager-service-connection-that-uses-workload-identity-federation) with either an app registration or managed identity instead of using an app registration with a secret. + +While a service account remains in use: +- **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). +- **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. +- **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). + +## Review auditing events + +Auditing can be used to track user actions, permissions changes, and usage patterns within your organization. Use these tools to identify and address potential security incidents promptly. + +- **[Enable auditing](../audit/azure-devops-auditing.md#enable-and-disable-auditing):** Track and view events related to user actions, permissions, changes, and security incidents. +- **[Review audit logs and streams regularly](../audit/azure-devops-auditing.md#review-audit-log):** 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. Learn more about the [auditing events we track](../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. + +## 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) + +## Automate security scanning + +Monitor for code and secret vulnerabilities with the following automated security tools built by our partner teams: + +- **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 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). + +## 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..3732030189c 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). +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#add-project-readme-files), 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..cfb512511c5 100644 --- a/docs/organizations/security/toc.yml +++ b/docs/organizations/security/toc.yml @@ -1,325 +1,260 @@ - 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 Best Practices + 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 + - name: About authentication, authorization, & security policies + displayName: concepts, understand, credentials, accounts, authorization, policies + href: about-security-identity.md + - name: Authentication types + displayName: permission, security, mechanism, type, application + href: ../../integrate/get-started/authentication/authentication-guidance.md?toc=/azure/devops/organizations/security/toc.json + 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: About managing access with Microsoft Entra ID + displayName: access, entra, id + href: ../accounts/access-with-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-microsoft-entra-id.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 - 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 - displayName: permission, security, mechanism, type, application - - 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 - - name: Manage PATs via API - href: ../accounts/manage-personal-access-tokens-via-api.md?toc=/azure/devops/organizations/security/toc.json - displayName: lifecycle, authenticate - - 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 - - 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 - - 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 - - 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 - displayName: authenticate, access, security -- name: Secure projects - items: - - 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 - - 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 - displayName: give, revoke, access, users - - name: Set dashboard permissions - href: ../../report/dashboards/dashboard-permissions.md?toc=/azure/devops/organizations/security/toc.json - displayName: access, users, view, settings - - 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: /azure/active-directory/add-users-azure-active-directory#delete-a-user?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: Look up Azure DevOps administrator + href: look-up-azure-devops-administrator.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 - - name: Manage access policies (cloud) + href: ../../marketplace/grant-permissions.md?toc=/azure/devops/organizations/security/toc.json + - name: Manage security policies (cloud) items: - - name: Manage security & app access policies - href: ../accounts/change-application-access-policies.md + - name: Manage security policies displayName: application, settings, add, update, remove + href: ../accounts/change-application-access-policies.md + - name: Setup Conditional Access policies + displayName: conditional, access, policies + href: ../accounts/conditional-access-policies.md + - name: Manage PAT policies + href: ../accounts/manage-pats-with-policies-for-administrators.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: Restrict organization creation + displayName: administrators, creating, organization + href: ../accounts/azure-ad-tenant-policy-restrict-org-creation.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: Revoke user PATs (for admins) + href: ../accounts/admin-revoke-user-pats.md +- name: Secure projects + items: + - 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 + - name: Set object-level permissions + displayName: artifacts, boards, repos, projects, area, iteration, path, work items, access + 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 + displayName: access, users, view, settings + href: ../../report/dashboards/dashboard-permissions.md?toc=/azure/devops/organizations/security/toc.json + - name: Set Wiki permissions + displayName: project, access, settings, users + href: ../../project/wiki/manage-readme-wiki-permissions.md??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..626790ce376 100644 --- a/docs/organizations/security/troubleshoot-permissions.md +++ b/docs/organizations/security/troubleshoot-permissions.md @@ -8,54 +8,56 @@ ms.topic: troubleshooting ms.author: chcomley author: chcomley monikerRange: '<= azure-devops' -ms.date: 02/24/2023 +ms.date: 02/10/2025 +ms.custom: sfi-image-nochange --- # 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 +66,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 +91,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 +105,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 +121,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 +139,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 +163,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 +179,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 +229,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 +245,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 +263,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..9e7fca52f33 100644 --- a/docs/organizations/security/view-permissions.md +++ b/docs/organizations/security/view-permissions.md @@ -1,86 +1,90 @@ --- 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 +ms.custom: sfi-image-nochange --- # 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 +92,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 +171,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 +186,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 +207,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..43264797e0a 100644 --- a/docs/organizations/settings/about-settings.md +++ b/docs/organizations/settings/about-settings.md @@ -7,7 +7,8 @@ ms.topic: overview ms.author: chcomley author: chcomley monikerRange: '<= azure-devops' -ms.date: 07/27/2022 +ms.date: 06/16/2025 +ms.custom: sfi-image-nochange --- # About settings for users, teams, projects, or organizations @@ -16,12 +17,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 +36,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 +65,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** @@ -97,12 +85,14 @@ Individual contributors can set their user preferences, enable features that are **Authentication** :::column-end::: :::column span="2"::: - - [Authenticate access with personal access tokens](../accounts/use-personal-access-tokens-to-authenticate.md) - [Authorize access to REST APIs with OAuth 2.0](../../integrate/get-started/authentication/oauth.md) + - [Authenticate access with Microsoft Entra tokens](../../integrate/get-started/authentication/entra.md) - [Use SSH key authentication](../../repos/git/use-ssh-keys-to-authenticate.md) + - [Authenticate access with personal access tokens](../accounts/use-personal-access-tokens-to-authenticate.md) :::column-end::: :::column span="2"::: - For an overview of supported authentication methods, see [Authentication overview](../../repos/git/auth-overview.md). + For an overview of supported authentication methods, see [Authentication overview](../../integrate/get-started/authentication/authentication-guidance.md). + [!INCLUDE [use-microsoft-entra-reduce-pats](../../includes/use-microsoft-entra-reduce-pats.md)] :::column-end::: :::row-end::: --- @@ -113,8 +103,10 @@ Individual contributors can set their user preferences, enable features that are **Authentication** :::column-end::: :::column span="2"::: - - [Authenticate access with personal access tokens](../accounts/use-personal-access-tokens-to-authenticate.md) + - [Authenticate access with Microsoft Entra tokens](../../integrate/get-started/authentication/entra.md) - [Use SSH key authentication](../../repos/git/use-ssh-keys-to-authenticate.md) + - [Manage OAuth app authorizations](manage-authorizations.md) + - [Authenticate access with personal access tokens](../accounts/use-personal-access-tokens-to-authenticate.md) :::column-end::: :::column span="2"::: For an overview of supported authentication methods, see [Authentication overview](../../repos/git/auth-overview.md). @@ -130,7 +122,6 @@ Individual contributors can set their user preferences, enable features that are - [Set personal or team favorites](../../project/navigation/set-favorites.md) :::column-end::: :::column span="2"::: - For an overview of supported authentication methods, see [Authentication overview](../../repos/git/auth-overview.md). :::column-end::: :::row-end::: --- @@ -144,18 +135,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, many 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 +180,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), [work in progress (WIP) limits](../../boards/boards/wip-limits.md). :::column-end::: :::row-end::: --- @@ -225,8 +215,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 +237,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 +285,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** @@ -330,7 +308,7 @@ From the administrative **Project settings** page, you can configure settings av - [Add a team administrator](add-team-administrator.md) :::column-end::: :::column span="2"::: - A default team is created when you create a project. You add a team when you want to provide a group of users in your organization a set of Agile tools, which they have full ownership to configure and manage. Teams have access to a product backlog, portfolio backlogs, sprint backlogs, dashboards, team-scoped widgets, and more. For an overview of all tools that support a team, see [About teams and Agile tools](about-teams-and-settings.md). + When you create a project, Azure DevOps automatically creates a default team. You can add more teams to give specific groups of users their own set of Agile tools, which they can fully configure and manage. Each team gets access to its own product backlog, portfolio backlogs, sprint backlogs, dashboards, team-scoped widgets, and more. For a complete overview of all tools available to teams, see [About teams and Agile tools](about-teams-and-settings.md). :::column-end::: :::row-end::: --- @@ -349,10 +327,11 @@ 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). + Project Administrators can add users to a project or a team. Adding a user to a team also adds them to the project. Users added at the project level can view and contribute only 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). :::column-end::: :::row-end::: --- @@ -364,7 +343,7 @@ From the administrative **Project settings** page, you can configure settings av - [Manage project-level notifications](../../organizations/notifications/manage-team-group-global-organization-notifications.md) :::column-end::: :::column span="2"::: - Many project-level notifications are automatically defined when a project is added. Notifications at the project-level are managed in much the same way as they are at the [team level](../../organizations/notifications/manage-team-group-global-organization-notifications.md). + Many project-level notifications are set up automatically when you create a project. You manage project-level notifications in the same way as [team-level notifications](../../organizations/notifications/manage-team-group-global-organization-notifications.md). :::column-end::: :::row-end::: --- @@ -376,7 +355,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::: --- @@ -388,7 +367,7 @@ From the administrative **Project settings** page, you can configure settings av - [Set default dashboard permissions](../../report/dashboards/dashboard-permissions.md) :::column-end::: :::column span="2"::: - New dashboards added to a project inherit the default dashboard permissions. The default permissions allow team members to create and edit dashboards for their team. + New dashboards added to a project automatically inherit the default dashboard permissions. By default, team members have permission to create and edit dashboards for their team. :::column-end::: :::row-end::: --- @@ -401,7 +380,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 +395,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 defined at the project level serve as defaults for teams. To configure more product backlogs, boards, or dashboards for specific groups, first [add a team](add-teams.md). :::column-end::: :::row-end::: --- @@ -425,7 +404,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) @@ -472,7 +451,7 @@ From the administrative **Project settings** page, you can configure settings av - [Request a Marketplace extension](../../marketplace/request-extensions.md) :::column-end::: :::column span="2"::: - Individual contributors and project administrators can request a Marketplace extension is installed. Only members of the Project Collection Administrators group can respond to these requests and actually install extensions. + Individual contributors and project administrators can request the installation of a Marketplace extension. However, only members of the Project Collection Administrators group can approve and install these extensions. :::column-end::: :::row-end::: --- @@ -500,7 +479,7 @@ From the administrative **Project settings** page, you can configure settings av - [Link GitHub commits, pull requests, and issues to work items](../../boards/github/link-to-from-github.md) :::column-end::: :::column span="2"::: - By connecting your Azure Boards project with GitHub.com repositories, you support 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. + By connecting your Azure Boards project to GitHub.com repositories, you enable linking between GitHub commits, pull requests, and Azure Boards work items. This integration allows you to use GitHub for source code development while using Azure Boards to plan and track your work. :::column-end::: :::row-end::: --- @@ -510,7 +489,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,11 +497,11 @@ From the administrative **Project settings** page, you can configure settings av :::row-end::: --- - + ## Project Collection Administrator (PCA) role and managing collections of projects -Members of the [**Project Collection Administrators** group](../security/change-organization-collection-level-permissions.md) configure resources for all projects that are defined for an organization or collection. They also can do all tasks to add projects, manage projects, and manage permissions for the collection, a project, a team, or an object. +Members of the [**Project Collection Administrators** group](../security/change-organization-collection-level-permissions.md) manage resources and settings for all projects within an organization or collection. They have full permissions to add and manage projects, configure resources, and set permissions at the collection, project, team, or object level. ::: moniker range="azure-devops" @@ -530,8 +509,7 @@ Members of the [**Project Collection Administrators** group](../security/change- From the administrative **Organization settings** page, you can configure settings available from the tabs shown in the following image and table. > [!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). - +> 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 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 +524,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 +576,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 +609,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 +620,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 +642,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 +697,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 +716,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 +736,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 +744,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 +784,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-artifacts-storage-limit). :::column-end::: :::row-end::: --- @@ -826,7 +792,7 @@ For an overview of managing collections, see [Configure and manage Azure DevOps ::: moniker range="< azure-devops" - + ## Server Administrator role @@ -840,9 +806,9 @@ For more information, see [Team Foundation Server Administration Documentation]( ## Related articles -- [Add and manage information banners](manage-banners.md) -- [Resources granted to project members](../projects/resources-granted-to-project-members.md) -- [Permissions and groups reference](../security/permissions.md) -- [Get started managing your project](../../user-guide/project-admin-tutorial.md) -- [Get started managing your organization or project collection](../../user-guide/manage-organization-collection.md) -- [Rate limits](../../integrate/concepts/rate-limits.md) +- [Add or update information banners](manage-banners.md) +- [Review resources granted to project members](../projects/resources-granted-to-project-members.md) +- [Configure permissions and groups](../security/permissions.md) +- [Manage your project](../../user-guide/project-admin-tutorial.md) +- [Manage your organization or project collection](../../user-guide/manage-organization-collection.md) +- [Monitor and manage rate limits](../../integrate/concepts/rate-limits.md) 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..5a9fe746c95 100644 --- a/docs/organizations/settings/add-team-administrator.md +++ b/docs/organizations/settings/add-team-administrator.md @@ -3,23 +3,24 @@ title: Add, remove team administrator titleSuffix: Azure DevOps description: Add another user to the team administrator role in Azure DevOps. ms.subservice: azure-devops-settings -ms.custom: teams ms.assetid: 843D5E56-D24E-4DEA-9915-19B1F76E9A56 ms.author: chcomley author: chcomley ms.topic: how-to monikerRange: '<= azure-devops' -ms.date: 04/04/2022 +ms.date: 11/12/2024 +ms.custom: + - teams + - sfi-image-nochange --- # 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 +28,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 +41,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 +52,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 +80,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 +99,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 +123,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 +145,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..0b06ab31f63 100644 --- a/docs/organizations/settings/add-teams.md +++ b/docs/organizations/settings/add-teams.md @@ -1,69 +1,64 @@ --- 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 ms.author: chcomley author: chcomley ms.topic: tutorial monikerRange: '<= azure-devops' -ms.date: 05/19/2022 +ms.date: 11/12/2024 +ms.custom: + - teams + - devx-track-azurecli + - sfi-image-nochange --- # 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 +71,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 +149,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 +162,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 +228,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 +242,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 +254,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 +265,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 +279,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 +303,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 +318,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 +341,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 +356,6 @@ If your deployment is integrated with SQL Server Reports, you need to [Grant per ::: moniker-end - ## Next steps > [!div class="nextstepaction"] @@ -407,10 +365,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..f4f7d9c79aa 100644 --- a/docs/organizations/settings/manage-authorizations.md +++ b/docs/organizations/settings/manage-authorizations.md @@ -7,58 +7,66 @@ 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 +ms.custom: sfi-image-nochange --- # 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 +76,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..e1859b1c0d4 100644 --- a/docs/organizations/settings/manage-teams.md +++ b/docs/organizations/settings/manage-teams.md @@ -1,19 +1,21 @@ --- 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 +ms.custom: + - teams + - sfi-image-nochange --- # 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 +29,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 +75,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 +110,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 +135,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 +188,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-post-2018.png b/docs/organizations/settings/media/agile-tools/agile-tools-team-assets-post-2018.png index dd69af44b53..9c0c1ced62a 100644 Binary files a/docs/organizations/settings/media/agile-tools/agile-tools-team-assets-post-2018.png and b/docs/organizations/settings/media/agile-tools/agile-tools-team-assets-post-2018.png 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..acf53e78dd9 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 @@ -51,21 +57,28 @@ For more information about reserved names, see [File names, paths, and namespace ## Azure Artifacts -Universal packages must conform to the following restrictions. +- Universal packages must conform to the following restrictions: + +| Restriction type | Restriction | +|--------------------|---------------| +|Package name |- Must be lowercase.
      - Must start and end with letters or numbers.
      - Must only contain letters, numbers, and nonconsecutive dashes, underscore, or periods. | +|Package version |- Must be lowercase without build metadata. | + +- Feeds must conform to the following restrictions: + +| Restriction type | Restriction | +|------------------|-------------| +| Feed name | - Feed names are NOT case sensitive; however, you cannot create a new feed with a name that differs only by capitalization from an existing feed.
      - Must start and end with a letter or number.
      - Cannot start with a '.' or '_', or end with a '.'.
      - Cannot include any of the following characters: @ ~ ; { } ' + = , < > \| / \ ? : & $ * " # [ ] %. | -|Restriction type |Restriction | -|---------|---------| -|Package name |- Must be lowercase.
      - Must start and end with letters or numbers.
      - Must only contain letters, numbers, and nonconsecutive dashes, underscore, or periods. | -|Package version |Must be lowercase without build metadata. | ## 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 +105,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 +168,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 +178,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 +229,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 +246,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 +272,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 +282,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 +294,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 +305,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 +362,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 +379,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 +387,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 +396,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 +406,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 +456,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..06753cc4664 100644 --- a/docs/organizations/settings/rename-remove-team.md +++ b/docs/organizations/settings/rename-remove-team.md @@ -8,29 +8,31 @@ ms.author: chcomley author: chcomley ms.topic: how-to monikerRange: '<= azure-devops' -ms.date: 04/04/2022 +ms.date: 11/12/2024 +ms.custom: sfi-image-nochange --- # 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 +47,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 +93,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 +187,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 +210,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 +260,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 +281,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..4bbc00acdb7 100644 --- a/docs/organizations/settings/set-area-paths.md +++ b/docs/organizations/settings/set-area-paths.md @@ -3,21 +3,26 @@ title: Define area paths and assign to a team titleSuffix: Azure Boards description: Group work items based on team, product, or feature area by defining area paths for Azure Boards and Azure DevOps. ms.subservice: azure-devops-settings -ms.custom: teams, engagement-fy23, devx-track-azurecli ms.assetid: 97358022-AE19-4775-AE25-47BA24FF3C74 ms.author: chcomley author: chcomley ms.topic: how-to monikerRange: '<= azure-devops' -ms.date: 02/10/2023 +ms.date: 11/14/2024 +ms.custom: + - teams + - engagement-fy23 + - devx-track-azurecli + - sfi-image-nochange --- # 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 +30,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 +93,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 +117,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 +179,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 +203,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 +217,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 +249,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 +265,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 +276,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 +349,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 +371,7 @@ Fabrikam Fiber\Voice True True [!INCLUDE [temp](../../includes/note-cli-not-supported.md)] -* * * - - - +--- ## Rename or move an Area Path @@ -477,11 +385,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 +398,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 +410,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 +427,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 +439,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 +457,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 +477,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 +488,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..84573a3a45a 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: 06/05/2025 --- # 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 your Azure DevOps user profile page, you can update your picture, display name, email address, language, date and time format, time zone, and other 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 +To set your preferences, do the following steps: ::: 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**. +1. From the home page, select :::image type="icon" source="../../media/icons/user-settings-gear.png" border="false"::: **User settings** > **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,52 @@ 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 option to use your profile picture, display name, contact email address, and region from Microsoft Entra in Azure DevOps. -3. From the **About** page, you can change the user profile picture, display name, contact information, and country/region. +To enable this feature, go to the Azure DevOps home page, select :::image type="icon" source="../../media/icons/user-settings-gear.png" border="false"::: **User settings**, then choose **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 experience issues with Microsoft Entra profile information, you can [turn it off](../../project/navigation/preview-features.md) and restore your original profile details. Provide detailed feedback if you do; we review all feedback to address 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 Azure DevOps updates and resources, check the box and select **Save**. + +Your user profile settings update. + +## 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) 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..09efb51b40d 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 @@ -8,51 +8,96 @@ ms.author: chcomley author: chcomley ms.topic: how-to monikerRange: 'azure-devops' -ms.date: 05/30/2018 +ms.date: 04/30/2025 --- # Change a project from Hosted XML to an inherited process [!INCLUDE [version-eq-azure-devops](../../../includes/version-eq-azure-devops.md)] -Once you've [cloned your Hosted XML process to an inherited process](upgrade-hosted-to-inherited.md), you can change the project(s) from the Hosted XML process to the inherited process. You change a project from a Hosted XML process to its derived inherited process to start customizing the process through the user interface. +Once you [clone your Hosted XML process to an inherited process](upgrade-hosted-to-inherited.md), you can change the project from the Hosted XML process to the inherited process. You change a project from a Hosted XML process to its derived inherited process to start customizing the process through the user interface. > [!CAUTION] -> Choosing to clone a project from a Hosted XML process model to an inherited process is an irreversible operation. Before you change the process of an existing project from Hosted XML to the cloned inherited process, review [Supported operations when moving from Hosted XML process to inherited process](upgrade-support-hosted-to-inherited.md) to understand which customizations are preserved and which are not before you change the process of a project from Hosted XML to an inherited process. Also, [create a test project](upgrade-hosted-to-inherited.md#verify) to verify the customizations preserved or reapplied to a process. +> Choosing to clone a project from a Hosted XML process model to an inherited process is an irreversible operation. Before you change the process of an existing project from Hosted XML to the cloned inherited process, review [Supported operations for moving from Hosted XML to an inherited process](#supported-operations-for-moving-from-hosted-xml-to-an-inherited-process), further in this article, to understand which customizations get preserved and which aren't before you change the process of a project from Hosted XML to an inherited process. Also, [create a test project](upgrade-hosted-to-inherited.md#verify) to verify the customizations preserved or reapplied to a process. ## 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)] + +## Supported operations for moving from Hosted XML to an inherited process + +Upgrading a Hosted XML process model to an inherited process allows you to customize your work tracking system through the user interface. For details on supported customizations, see [About process customization and inherited processes](inheritance-process-model.md). + +While the clone process preserves most work tracking customizations, some advanced customizations from the Hosted XML process might not be supported. Additionally, certain customizations must be manually recreated in the inherited process. + +### Customizations preserved during clone + +When you clone a Hosted XML process to an inherited process, the customizations listed in the following table are preserved. + +|Artifact| Description | +|------|---------| +| 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 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. | +| Default properties | The default properties set for teams that you add to a project are preserved as documented in [Process configuration XML element reference, Specify properties, and behaviors](../../../reference/xml/process-configuration-xml-element.md#specify-properties-and-behaviors). | + +### Customizations ignored during clone + +|Artifact| Description | +|------|---------| +| Header area customization | Any customizations made to the header area within the work item form are ignored. The header area, as shown in the following image, gets managed by the system. Any customizations made within the **SystemControls** section of the **WebLayout** are ignored.

      ![Work item web form, Header area](media/migration/header-area.png) | +| Four column layout and size | The inherited process supports a [a fixed relative sizing of three columns](inheritance-process-model.md#resizing) to a WIT layout, while the Hosted XML process supports up to four columns and allows you to set the first column as equal sized with the rest of the columns. | +| Hide Details page in layout | The inherited process ignores any customizations made to hide the Details page in a WIT layout. | +| Workflow restriction | The inherited process follows an any-to-any workflow state transition. Any customizations that restrict the transition from one workflow state to another are ignored. | +| Workflow state reasons | Customized reasons added to workflow states are ignored. | +| Conditional picklists | Conditional picklists, also referred to as dependent or cascading picklists, are ignored. Multiple sets of allowed values per field are ignored. Picklists are defined for a field at the collection level and shared across processes and WITs. | +| Custom rules | All custom rules to fields and workflow are ignored. | +| Custom link controls | Custom link controls are ignored. | +| 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 aren't 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 aren't supported in any work item type other than Test Case. | + ## 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. +After you verify your customizations, you can apply the inherited process to your existing project. 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**. + + > [!div class="mx-imgBorder"] + > ![Screenshot showing highlighted Organization settings button.](../../../media/settings/open-admin-settings-vert.png) -1. From **Process**, choose the original Hosted XML process, then choose the **Projects** page. +3. Select **Process** and choose the original Hosted XML process. +4. Select the **Projects** page. > [!div class="mx-imgBorder"] - > ![Open inherited process, Projects page](media/migration/open-processes-projects-page.png) + > ![Screenshot shows Open inherited process, Projects page.](media/migration/open-processes-projects-page.png) -1. Open the … context menu for the project and choose the **Change process**… option. +5. Open the … context menu for the project and choose the **Change process**… option. Here we open the menu for the Fabrikam Test project. > [!div class="mx-imgBorder"] > ![Fabrikam Test project context menu, Choose Change process](media/migration/change-project-process-to-inherited.png) -2. Choose the inherited process that you created. The system lists only those processes that are valid for the selected project. +6. Choose the inherited process that you created. The system lists only those processes that are valid for the selected project. > [!div class="mx-imgBorder"] > ![Change process to an inherited process dialog](media/migration/change-process-dialog.png) -3. Choose **Ok**. +7. Select **Ok**. +[!INCLUDE [temp](../includes/post-upgrade-steps.md)] ## Related articles -- [Supported operations when moving from Hosted XML process to an inherited process](upgrade-support-hosted-to-inherited.md) -- [Clone a Hosted XML process to an Inheritance process](upgrade-hosted-to-inherited.md) +- [About process customization and inherited processes](inheritance-process-model.md) 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..d614734d776 100644 --- a/docs/organizations/settings/work/customize-process-field.md +++ b/docs/organizations/settings/work/customize-process-field.md @@ -1,29 +1,30 @@ --- -title: Add and manage fields to an inherited process +title: Add and Manage Fields for an Inherited Process titleSuffix: Azure DevOps -description: Add and manage fields in the web form of a work item type for an Inheritance process +description: Learn how to add and manage fields in the web form of a work item type for an Inheritance process. ms.custom: inherited-process 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 +ms.date: 05/08/2025 --- # Add and manage fields (Inheritance process) [!INCLUDE [version-gt-eq-2019](../../../includes/version-gt-eq-2019.md)] -You can add a custom field to support tracking additional data requirements or modify select attributes of an ![inherited icon](media/process/inherited-icon.png) inherited field. For example, you can add a custom field or change the label that appears in the work item form for an inherited field. +You can customize your work tracking system by adding custom fields or modifying specific attributes of an ![inherited icon](media/process/inherited-icon.png) inherited field. For example, you can add a custom field to capture other data or change the label displayed in the work item form for an inherited field. [!INCLUDE [temp](../includes/note-on-prem-link.md)] -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#review-fields). +To view all fields defined for your organization, including system and inherited fields, see [View work item fields and attributes](../../../boards/work-items/work-item-fields.md#review-fields). -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. +After you add a custom field, you can use it to 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 and analyze related data. +## Prerequisites [!INCLUDE [temp](../includes/process-prerequisites.md)] @@ -31,77 +32,71 @@ 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. +When you add a custom field to an inherited process, Azure DevOps assigns it a reference name prefixed with *Custom* and removes any spaces from the field name. For example, a field named "DevOps Triage" is assigned the reference name **Custom.DevOpsTriage**. Spaces aren't allowed in reference names. ## Add a custom field -You can add fields and specify the group and page where they should appear. Also, once you've added a field, you can drag-and-drop it within a page to move its placement within the form. If you have several fields you want to add to a custom page or group, then [add those pages or groups first](customize-process-form.md) and then add your fields. +You can add fields and specify the group and page where they should appear. After you add a field, you can drag and drop it within a page to adjust its placement on the form. If you plan to add multiple fields to a custom page or group, [create those pages or groups first](customize-process-form.md) before adding the fields. -> [!NOTE] -> Each process can define up to 1024 fields, including system inherited fields. You can only add fields within a page on a form. You can't add a field to the gray area within the form where the Assigned To, State, and Reason fields are located. +Each process can define up to 1,024 fields, including system and inherited fields. Fields can only be added within a page on a form. You can't add fields to the gray area of the form where the Assigned To, State, and Reason fields are located. -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, select the work item type (WIT) where you want to add the custom field. - Here we choose the Bug WIT. Note the breadcrumb links that allow you to move back to All Processes and MyAgile process page. + In the following example, we select the Bug WIT. Notice the breadcrumb links that allow you to navigate back to **All Processes** and the **MyAgile** process page. - > [!div class="mx-imgBorder"] - > ![All Processes-Process-WIT breadcrumb links](media/field/breadcrumbs-bug-wit.png) + > [!div class="mx-imgBorder"] + > ![Screenshot shows breadcrumb links for All Processes, Process, and WIT.](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](../../../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) + > [!div class="mx-imgBorder"] + > ![Screenshot shows the Process Work Item Types page with the option to 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. Optionally, add a description. +3. Name the field and select the field type from one of the supported data types. Optionally, add a description. - > [!NOTE] - > You must specify a field name that is unique within the organization. A custom field defined for one process cannot be the same as the name defined for another process. For more information on field names, see [What is a field? How are field names used?](inheritance-process-model.md#field-reference) - - Here we add an Integer field labeled Customer Ticket. + Field names must be unique within the organization. A custom field in one process can't share the same name as a field in another process. For more information, see [What is a field? How are field names used?](inheritance-process-model.md#field-reference). - Add a field to Bug, choose field type + In the following example, we add an Integer field type labeled *Customer Ticket*. - -1. (Optional) On the Options tab, indicate if the field is required and specify a default value. Or leave the values blank. By making a field **Required**, users must specify a value for the field to save the work item. When you create a work item as well as every time someone opens a work item and the field is empty, the default value is set. + ![Screenshot shows adding a field to the Bug WIT and selecting the Integer field type.](media/process/cpfield-add-field-to-bug-type-integer-up1.png) + - Add a field to Use story, specify options +4. (Optional) On the **Options** tab, indicate whether the field is required and specify a default value. If left blank, the field remains optional. When you make a field **Required**, users must specify a value to save the work item. The default value is set when a work item is created or 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. + ![Screenshot shows setting options for the Customer Ticket field.](media/process/cpfield-bug-customer-ticket-options.png) + - Here, we add the Customer Ticket field to a new group labeled Customer focus. +5. (Optional) On the **Layout** tab, you can specify a different form label than the field name. You can also choose the page and group where the field appears on the form. - Add a field to Use story, specify layout + In the following example, we add the Customer Ticket field to a new group labeled Customer focus. - > [!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. + ![Screenshot shows adding the Customer Ticket field to the Customer focus group in the layout.](media/process/cpfield-customer-ticket-layout.png) -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. + > [!NOTE] + > While you can change the form label, you must use the field name when 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. When you've completed making all your changes, open a work item of the type you've customized. +6. Choose **Add field** to complete the process. If you don't specify a layout location, the system adds the field to the first group of fields on the form. - Here, we show the Customer Ticket field has been added to the Status group. You may need to refresh your browser to see the changes. +7. After your changes are complete, open a work item of the customized type to review the updates. - > [!div class="mx-imgBorder"] - > ![Bug form, Customer Ticket field added to Customer focus group](media/process/cpfield-bug-form-customized-customer-ticket.png) + The following example shows the Customer Ticket field was successfully added to the Status group. If the changes aren't immediately visible, refresh your browser to ensure the updates display correctly. This step ensures the new field is properly integrated into the work item form and ready for use. + > [!div class="mx-imgBorder"] + > ![Screenshot shows the Bug form with the Customer Ticket field added to the 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" @@ -110,129 +105,112 @@ You can add a new field and define a pick list or customize the pick list of an ::: moniker-end -> [!NOTE] -> Each organization or collection can define up to 2048 picklists. Each picklist can contain up to 2048 items. Picklist items must be 256 or fewer characters. If you want to add dependent picklists, see [Cascading lists](https://marketplace.visualstudio.com/items?itemName=ms-devlabs.cascading-picklists-extension). +Each organization or collection can define up to 2,048 picklists. Each picklist can contain up to 2,048 items. Picklist items must be 256 or fewer characters. To add dependent picklists, see [Cascading lists](https://marketplace.visualstudio.com/items?itemName=ms-devlabs.cascading-picklists-extension). -1. Start by choosing ![add new field icon](media/process/new-field-icon.png) New field, then specify the picklist type—integer or string—and then add the items to appear in the picklist. You can add an item and then press **Enter** to add another item. +1. Select ![add new field icon](media/process/new-field-icon.png) **New field**, then specify the picklist type—integer or string—and then add the items to appear in the picklist. You can add an item and then select **Enter** to add another item. - ![Add a field to Bug dialog, Add a custom picklist.](media/process/add-a-field-pick-list-up1.png) + ![Screenshot shows Add a field to Bug dialog, Add a custom picklist.](media/process/add-a-field-pick-list-up1.png) - To delete an item in the list, highlight the item and then click the ![Delete icon](../../../media/icons/delete_icon.png) delete icon. + To delete an item in the list, highlight the item and then select the ![Delete icon](../../../media/icons/delete_icon.png) delete icon. ::: moniker range=">= azure-devops-2020" To modify the pick list of an inherited field, choose **Edit** to edit the field. On the **Definition** tab, you can choose to **Add value**. > [!div class="mx-imgBorder"] - > ![Edit field Priority in User STory dialog, Definition tab.](media/field/edit-priority-picklist.png) + > ![Screenshot shows Edit field Priority in User Story dialog, Definition tab.](media/field/edit-priority-picklist.png) ::: moniker-end -2. (Optional) Choose the **Options** tab to define the field as required, specify a default, or allow users to enter their own values. - - ![Allow values in a custom picklist](media/process/add-a-field-pick-list-options.png) - -3. (Optional) See previous [step 5](#layout) to specify where you want the field to appear on the form (**Layout** tab). - - +2. (Optional) Specify [required or default values](#required-default) and [choose where the field appears on the form](#options). + ![Screenshot shows Allow values in a custom picklist.](media/process/add-a-field-pick-list-options.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. - -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. +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. - ![Add a field to Bug dialog, Definition tab, Add an Identity field.](media/process/cpfield-identity.png) +Select ![add new field icon](media/process/new-field-icon.png) **New field**, then the field name, Identity type, and optionally a description. -1. (Optional) See previous [step 5](#layout) to specify where you want the field to appear on the form (Layout tab). + ![Screenshot shows Add a field to Bug dialog, Definition tab, Add an Identity field.](media/process/cpfield-identity.png) +(Optional) Specify [required or default values](#required-default) and [choose where the field appears on the form](#options). ### Add a rich-text, HTML field -1. As before, choose the WIT you want to add the field to and then choose the ![add new field icon](media/process/new-field-icon.png) New field. +1. Select the WIT you want to add the field to, and then choose the ![add new field icon](media/process/new-field-icon.png) **New field**. -1. Choose Text (multiple lines) as the type. Here we label the field as Customer request to capture customer comments for product feature requests. +2. Choose Text (multiple lines) as the type. Here we label the field as Customer request to capture customer comments for product feature requests. - ![Process Work Item Types page, Add a rich-text field to the Bug form](media/process/cpfield-add-html-field-to-bug.png) + ![Screenshot shows Process Work Item Types page, Add a rich-text field to the Bug form.](media/process/cpfield-add-html-field-to-bug.png) -1. The field is added to the first column under all system-defined rich-text fields, but before the Discussion control. +3. The field gets added to the first column under all system-defined rich-text fields, but before the Discussion control. - > [!div class="mx-imgBorder"] - > ![Bug form, Customer request field added to first column in form](media/process/customize-process-field-show-custom-html-field-up1.png) + > [!div class="mx-imgBorder"] + > ![Screenshot shows Bug form, Customer request field added to first column in form.](media/process/customize-process-field-show-custom-html-field-up1.png) + +4. (Optional) Specify [required or default values](#required-default) and [choose where the field appears on the form](#options). ### Add a checkbox field -1. As before, choose the WIT you want to add the field to and then choose ![add icon](../../../media/icons/green_plus_icon.png) New field. +1. Select the WIT you want to add the field to, and then choose ![add icon](../../../media/icons/green_plus_icon.png) **New field**. 2. Choose Boolean as the type, and give it a label. Here we label the field as Triaged to track the triage state of the bug. - Add a boolean field + ![Screenshot shows adding a boolean field.](media/process/cpfield-add-boolean-field-to-bug.png) -3. (Optional) Open the Options tab and specify if the field should be required. +3. (Optional) Select **Options**, and then specify whether the field is required. - ![Set options for boolean field](media/process/cpfield-edit-boolean-field-options-up1.png) + ![Screenshot shows setting options for boolean field.](media/process/cpfield-edit-boolean-field-options-up1.png) -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. +4. By default, the field gets added to the last group defined in the second column. Select **Layout**, and then 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). + > [!NOTE] + > The field appears as a checkbox in the work item form. Selecting the checkbox indicates a *True* value. If the field displays on the board or Taskboard, the values *True* and *False* show as text instead of a checkbox. ## Add an existing field to another WIT -Existing fields correspond to any inherited field and custom field defined within the collection. Once you've added a custom field to one WIT, you can add it to others from the form menu. Or, you can add a field defined for one process to a work item type in another process. Open the work item type and choose the existing field. +Existing fields correspond to any inherited field and custom field defined within the collection. After you add a custom field to one WIT, you can add it to others from the form menu. Or, you can add a field defined for one process to a work item type in another process. Open the work item type and choose the existing field. To look up descriptions of any system-defined work item field, see the [Work item field index](../../../boards/work-items/guidance/work-item-field.md). -Here we add the Customer Ticket field to the User Story WIT. - -![Add existing field to a User Story](media/process/cpfield-add-existing-field.png) +In the following example, 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. +![Screenshot shows adding existing field to a User Story.](media/process/cpfield-add-existing-field.png) +(Optional) Specify [required or default values](#required-default) and [choose where the field appears on the form](#options). ## Relabel a field -Renaming a field or changing the field type aren't supported actions. However, from the **Layout** tab you can change the label that appears on the work item form. When selecting the field in a query, you need to select the field name and not the field label. +Renaming a field or changing its type isn't supported. However, you can change the label displayed on the work item form from the **Layout** tab. When creating queries, use the field name, not the label. -Here, we relabel the Customer Ticket field to Ticket Number. +In the following example, we relabel the *Customer Ticket* field to *Ticket Number*. -![Layout tab, Relabel a field](media/process/cpfield-relabel-customer-ticket.png) - +![Screenshot shows Layout tab, with relabeled a field.](media/process/cpfield-relabel-customer-ticket.png) - + ## Modify Description help text ::: moniker range=">= azure-devops-2020" -Description help text displays when users hover over a field in the work item form. You can define different help text for the same fields for different work item types. Modification is supported for both custom fields and inherited fields. Note that the implementation differs based on the field type. -- **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. - +Description help text appears when users hover over a field in the work item form. You can customize help text for both custom and inherited fields, but the behavior differs by field type: +- **Inherited fields**: Help text can be customized for each work item type and process. +- **Custom fields**: Help text is consistent across all work item types and 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,51 +222,26 @@ 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 ::: moniker range=">= azure-devops-2020" -You can choose to show or hide any field or custom control from appearing on a form. If you want to reinstate a field onto the form later, you can un-hide These actions differ from the [**Delete**](#delete-field) option, which deletes the field from the organization. - -::: 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. +You can choose to show or hide any field or custom control from appearing on a form. If you want to reinstate a field onto the form later, you can unhide 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). - - +> When you remove a custom field from the layout, it gets 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 gets 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 +::: moniker-end 1. Open the context menu for the field or control and choose **Hide from layout**. @@ -310,43 +263,43 @@ 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 -You may discard changes you made to an inherited field. From the **Layout** page of the modified work item type, choose the **Revert** option for the field. +You can discard changes you made to an inherited field. From the **Layout** page of the modified work item type, choose the **Revert** option for the field. > [!div class="mx-imgBorder"] -> ![Layout page, Field context menu, choose Revert option](media/process/cpfield-revert.png) - +> ![Screenshot shows Layout page, Field context menu, choose Revert option.](media/process/cpfield-revert.png) ## Delete a custom field -With the Inheritance process model, you can only delete custom fields. You can't delete fields defined for system default processes. +With the Inheritance process model, you can only delete custom fields; you can't delete system default fields. -Deleting a field deletes all data associated with that field, including historical values. Once deleted, you can only restore the field and recover the data using the [Fields - Update REST API](/rest/api/azure/devops/wit/fields/update). +Deleting a field removes all associated data, including historical values. There might be a short delay before data purge jobs begin. During this time, you can attempt to restore the field and recover its data using the [Fields - Update REST API](/rest/api/azure/devops/wit/fields/update). Recovery might be full, partial, or unsuccessful, depending on the remaining data. Use caution when deleting fields, as recovery isn't always possible or complete. -> [!NOTE] -> We recommend that you only delete fields that are not in use. You can determine fields that aren't in use by exercising the **witadmin listfields** command. To learn how, see [Manage work item fields (witadmin)](../../../reference/witadmin/manage-work-item-fields.md). -> Or, if Analytics is enabled for your organization or collection, you can query Analytics for where a custom field is in use with the following syntax: +> [!NOTE] +> This action CANNOT be undone. Delete only fields that aren't in use. Use the **witadmin listfields** command to identify unused fields. For more information, see [Manage work item fields (witadmin)](../../../reference/witadmin/manage-work-item-fields.md). +> If Analytics is enabled for your organization or collection, you can query Analytics to find where a custom field is in use with the following syntax: + > [!div class="tabbedCodeSnippets"] > ```OData > https://analytics.dev.azure.com/{OrganizationName}/_odata/v4.0-preview/WorkItemTypeFields?$filter=FieldReferenceName eq {CustomFieldReferenceName}&$select=WorkItemType > ``` +To delete a custom field, do the following steps: -1. You delete the field from the **All processes>Fields** page. +1. Select **Organization settings** > **Process** > **Fields** > :::image type="icon" source="../../../media/icons/actions-icon.png" border="false"::: **More actions** > **Delete**. ![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). + Be a member of the Project Collection Administrators group or [granted explicit permissions to Delete fields](../../../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. +2. Enter the name of the field as shown in the following example, and then confirm by selecting **Delete work item field**. - ![Delete field, confirmation dialog](media/process/cpfield-delete-confirmation.png) + ![Screenshot shows Delete field, confirmation dialog.](media/process/cpfield-delete-confirmation.png) ## Related articles @@ -355,21 +308,11 @@ Deleting a field deletes all data associated with that field, including historic - [View work item fields and attributes](../../../boards/work-items/work-item-fields.md) - [Add or modify a custom work item type](customize-process-work-item-type.md) -- [Customize the web layout](customize-process-form.md) -- [Customize a project using an inherited process](customize-process.md) -- [Customize cards on boards](../../../boards/boards/customize-cards.md) -- [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) - +- [Customize the web layout](customize-process-form.md) +- [Work tracking, process, and project limits](object-limits.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/hosted/toc.yml b/docs/organizations/settings/work/hosted/toc.yml index cdc12159ac7..0481b81e292 100644 --- a/docs/organizations/settings/work/hosted/toc.yml +++ b/docs/organizations/settings/work/hosted/toc.yml @@ -1,7 +1,5 @@ - name: Hosted XML process overview href: ../hosted-xml-process-model.md -- name: Differences between Server and Service - href: ../import-process/differences.md - name: Differences between Hosted XML and Inherited href: ../inheritance-versus-hosted-xml.md - name: Customize a Hosted XML process @@ -12,8 +10,6 @@ href: ../import-process/resolve-errors.md - name: Migrate Hosted XML to inherited items: - - name: Supported clone operations - href: ../upgrade-support-hosted-to-inherited.md - name: Clone a Hosted XML process to Inheritance href: ../upgrade-hosted-to-inherited.md - name: Change a project from Hosted XML to Inheritance diff --git a/docs/organizations/settings/work/import-process/customize-process.md b/docs/organizations/settings/work/import-process/customize-process.md index d1775b45a55..d66db9cab2e 100644 --- a/docs/organizations/settings/work/import-process/customize-process.md +++ b/docs/organizations/settings/work/import-process/customize-process.md @@ -1,111 +1,77 @@ --- title: Customize a process that imports by using Hosted XML titleSuffix: Azure DevOps Services -description: Customize a Hosted XML process to support custom fields, work item types, global lists, and process configuration +description: Customize a Hosted XML process to support custom fields, work item types, global lists, and process configuration. ms.service: azure-devops-boards ms.custom: engagement-fy23 ms.assetid: AA5B592D-8F76-4974-9918-B8B523A6F23F +ai-usage: ai-assisted ms.topic: how-to ms.author: chcomley author: chcomley monikerRange: 'azure-devops' -ms.date: 01/17/2023 +ms.date: 04/29/2025 --- # Customize a Hosted XML process [!INCLUDE [version-eq-azure-devops](../../../../includes/version-eq-azure-devops.md)] -Azure DevOps Services supports adding and updating processes through an administrative experience that is a web-based [import process](import-process.md). After you add a process, you can create one or more projects from it. You can update the process at any time by importing it again. The changes made to the process template are then applied to all projects that use the process. +Azure DevOps supports adding and updating processes through an administrative experience that is a web-based [import process](import-process.md). After you add a process, you can create one or more projects from it. You can update the process at any time by importing it again. The changes made to the process template are then applied to all projects that use the process. > [!IMPORTANT] -> With the Hosted XML process model, you customize work tracking by updating select XML definition files of a process template. This feature is available only when data is migrated to Azure DevOps Services by use of [Team Foundation Server Database Import Service](../../../../migrate/migration-overview.md). +> With the Hosted XML process model, you customize work tracking by updating select XML definition files of a process template. This feature is available only when data gets migrated to Azure DevOps Services by use of [Azure DevOps Data Migration Tool](../../../../migrate/migration-overview.md). +> If you use the Inheritance process model, you can customize your work tracking through the user interface by [creating an Inheritance 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 customization and process models, see [Customize work tracking](../../../../reference/customize-work.md). - -A process is a zip file that contains a set of interdependent files. These files define the building blocks of the work-item tracking system and other subsystems in Azure DevOps Services. Some building blocks update existing projects, while others apply only to new projects. See the following table for the full list of building blocks. - -:::row::: - :::column span="1"::: - **Used when importing/updating a process** - :::column-end::: - :::column span="1"::: - **Used when creating a new project** - :::column-end::: - :::column span="1"::: - **Replaced by system defaults** - :::column-end::: - :::column span="1"::: - **Ignored** - :::column-end::: -:::row-end::: -:::row::: - :::column span="1"::: - - Work Item Tracking - - WITs - - Categories - - Process Configuration - - :::column-end::: - :::column span="1"::: - - Areas and Iterations - - Test Management +>For more information about customization and process models, see [Customize work tracking](../../../../reference/customize-work.md). - Work Items +A process is a zip file that contains a set of interdependent files. These files define the building blocks of the work-item tracking system and other subsystems in Azure DevOps. Some building blocks update existing projects, while others apply only to new projects. See the following table for the full list of building blocks: - Work Item Queries +| **Used when importing/updating a process** | **Used when creating a new project** | **Replaced by system defaults** | **Ignored** | +|------------|------------------------|-------------------------|-------------| +| Work Item Tracking | Areas and Iterations | Build | Microsoft Project Mappings | +| Work item types (WITs) | Test Management | Lab Management | Reports | +| Categories | Work Items | Version Control | Portal (SharePoint Products) | +| Process Configuration | Work Item Queries | | | - :::column-end::: - :::column span="1"::: - - Build - - Lab Management +## Prerequisites - Version Control - - :::column-end::: - :::column span="1"::: - - Microsoft Project Mappings +[!INCLUDE [process-prerequisites](../../includes/process-prerequisites.md)] - Reports - - Portal (SharePoint Products) +## Customize a process - :::column-end::: -:::row-end::: +Customizing a process is more efficient when you start with a well-defined process rather than building one from scratch. -![Supported process plug-ins and objects for process import](media/ALM_IP_SupportedPlugins.png) +If you're updating an existing process previously used with Azure DevOps Server, ensure it adheres to the [constraints required for template import](#rule-summary) to avoid validation errors during the import process. -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). + -## How to customize a process +### Export and import a process -When you customize a process, starting with a well-defined process is easier than building a new one. +Do the following steps to import or export a process: -If you update an existing process you've used with on-premises Team Foundation Server, make sure it conforms to the [constraints placed on templates for import](#rule-summary). +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"] + > ![Screenshot shows highlighted Organization settings button.](../../../../media/settings/open-admin-settings-vert.png) -[!INCLUDE [temp](../../includes/open-process-admin-context-ts-only.md)] +3. Select **Process**. + + > [!div class="mx-imgBorder"] + > ![Screenshot shows Organization settings, Process page.](/azure/devops/organizations/settings/work/media/process/open-process-page-s150.png) -### Export and import a process + > [!IMPORTANT] + > 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). -1. From the **Processes** tab, select the ellipsis (...) to open the shortcut menu for the Hosted XML process that you want to export. You can export only Hosted XML processes. +4. Select the ellipsis (...) to open the shortcut menu for the Hosted XML process that you want to export. You can export only Hosted XML processes. > [!div class="mx-imgBorder"] > ![Process page > Export Hosted XML process menu option ](media/export-process.png) Save the zip file and extract all files from it. -1. Rename the process within the ProcessTemplate.xml file located in the root directory. +5. Rename the process within the ProcessTemplate.xml file located in the root directory. Name the process to distinguish it from existing ones. @@ -115,11 +81,11 @@ If you update an existing process you've used with on-premises Team Foundation S `````` -1. Apply [supported customizations](#supported-customizations). +6. Apply [supported customizations](#supported-customizations). -1. Create a zip file of all files and folders in the root directory. +7. Create a zip file of all files and folders in the root directory. -1. [Import the zip file of your custom process](import-process.md). +8. [Import the zip file of your custom process](import-process.md). @@ -127,14 +93,23 @@ If you update an existing process you've used with on-premises Team Foundation S You can apply the following customizations to your process: -* [Add, remove, or modify a WIT](../../../../reference/add-modify-wit.md). -* [Add or modify a field](../../../../reference/add-modify-wit.md). -* [Add up to five portfolio backlogs](../../../../reference/add-portfolio-backlogs.md). -* [Add categories](/previous-versions/azure/devops/reference/xml/use-categories-to-group-work-item-types) that you'll use in your process configuration. -* [Modify process configuration](../../../../reference/xml/process-configuration-xml-element.md). -* [Add global lists](/previous-versions/azure/devops/reference/xml/define-global-lists). +* [Add, remove, or modify a WIT](../../../../reference/add-modify-wit.md) +* [Add or modify a field](../../../../reference/add-modify-wit.md) +* [Add up to five portfolio backlogs](../../../../reference/add-portfolio-backlogs.md) +* [Add categories](/previous-versions/azure/devops/reference/xml/use-categories-to-group-work-item-types) that you use in your process configuration +* [Modify process configuration](../../../../reference/xml/process-configuration-xml-element.md) +* Add global lists + +## Differences + +Azure DevOps Services and Azure DevOps Server use different models for relating projects and processes: +- In Azure DevOps Server, process templates serve as starting points for projects, and customization is scoped to individual projects. +- In Azure DevOps Services, processes are shared across multiple projects and serve as the scope for customization. -The following section lists limitations that the system imposes. +The structure and syntax for defining process templates are mostly consistent, with only minor differences between templates designed for Azure DevOps Services and Azure DevOps Server. + +> [!NOTE] +> Migration from Hosted XML to the inherited model is supported only in Azure DevOps Services, not in Azure DevOps Server. @@ -143,20 +118,41 @@ 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) +## Unsupported customizations and unreferenced plug-in files + +Any reference to the following objects in any of the XML definition files result in a validation error upon import: +* Custom controls on work item forms +* Custom link types +* Global workflow +* Team field support +* *For* and *Not* rules +* Match rule support + +The following plug-ins and their associated files aren't used in defining a process, nor used to update existing projects: +However, they're used to create objects or artifacts when you create a new project. +* Classification +* Work item queries, defined using the Work Item Query Language (WIQL) syntax +* Test Management +* Work items + +> [!NOTE] +> The WIQL length must not exceed 32-K characters. The system doesn't allow you to create or run queries that exceed that length. + +The following plug-ins and their associated files get replaced by system defaults: +* Build +* Groups and Permissions +* Lab +* Version Control + +The following plug-ins and their associated files are ignored: +* Microsoft Project Mappings +* Reports +* Windows SharePoint Services + +Custom plug-ins aren't supported. + +### Object limits +When customizing a process template for import, limit the number of the objects you define as specified in [Work tracking object limits](../object-limits.md). @@ -176,7 +172,7 @@ Also, your process must pass the following validation checks: * A template with the same name but a different version GUID generates an error. * Process names can't contain the following special characters: ```. , ; ' ` : / \ * | ? " & % $ ! + = ( ) [ ] { } < >```.\ - See [Naming restrictions](../../naming-restrictions.md) for additional constraints. + See [Naming restrictions](../../naming-restrictions.md) for more constraints. * Process folders contain no .exe files. Even if you can import a process that contains an .exe file, project creation fails. * The process's total size is at most 2 GB. Otherwise, project creation fails. @@ -186,7 +182,7 @@ Also, your process must pass the following validation checks: The ProcessConfiguration.xml definition file must conform to the syntax and rules described in [ProcessConfiguration XML element reference](../../../../reference/xml/process-configuration-xml-element.md). Also, it must meet the following conditions: -* Specifies all **TypeFields** elements +* Specifies all `TypeFields` elements * Is limited to five portfolio backlogs * Contains only one unparented portfolio backlog * Specifies only one parent portfolio backlog for each subordinate portfolio backlog @@ -199,73 +195,70 @@ The ProcessConfiguration.xml definition file must conform to the syntax and rule The Categories.xml definition file must conform to the syntax and rules described in [Categories XML element reference](/previous-versions/azure/devops/reference/xml/categories-xml-element-reference). Also, it must meet the following conditions: * Is limited to 32 categories -* Defines all categories referenced in the ProcessConfiguration.xml file +* Defines all categories referenced in the ProcessConfiguration.xml definition file ### Work item types -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: +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. -* 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*. +* There are at most 1,024 fields within a single WIT and 1,024 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. -* The **WITD** element contains a **FORM** element that defines a **WebLayout** element conforming to the syntax specified in [WebLayout and Control elements](/previous-versions/azure/devops/reference/xml/weblayout-xml-elements). +* The `WITD` element contains a `FORM` element that defines a `WebLayout` element conforming to the syntax specified in [WebLayout and Control elements](/previous-versions/azure/devops/reference/xml/weblayout-xml-elements). ### Work item fields -A **FIELDS** element and its child elements must conform to the syntax and rules described in [FIELD XML element reference](/previous-versions/azure/devops/reference/xml/field-definition-element-reference). Also, it must meet the following conditions: +A `FIELDS` element and its child elements must conform to the syntax and rules described in [FIELD XML element reference](/previous-versions/azure/devops/reference/xml/field-definition-element-reference). Also, it must meet the following conditions: -* 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*. +* 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. -A **FIELD** element and its child elements can contain a **GLOBALLIST** element. +A `FIELD` element and its child elements can contain a `GLOBALLIST` element. #### Limit restrictions -* A **FIELDS** element is limited to 512 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 `FIELDS` element is limited to 1,024 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. #### Required fields -The following fields are specified in the ProcessConfiguration.xml file: - -* For all WITs in a category that defines a process-configuration backlog, specify the fields used for the attributes and values ```type=Team``` and ```type=Order```. -* For all WITs in a category that defines a regular backlog or portfolio backlog, specify the field used for ```type=Effort```. -* For all WITs in the category that defines the **TaskBacklog** element, specify: - * The field used for ```type=RemainingWork```. - * The field used for ```type=Activity```. - * The **ALLOWEDVALUES** rule for the field used for ```type=Activity```. +| Category | Fields to specify | +|-----------|---------------------------| +| Process-configuration backlog | Fields used for the attributes and values `type=Team` and `type=Order` | +| Regular backlog or portfolio backlog | Field used for `type=Effort` | +| TaskBacklog | - Field used for `type=RemainingWork`
      - Field used for `type=Activity`
      - `ALLOWEDVALUES` rule for the field used for `type=Activity` | #### Rule restrictions -In addition to the standard [field-rule restrictions](../rule-reference.md), the following restrictions are enforced: - -* Field-rule elements can't specify the **for** and **not** attributes. -* **FIELD** elements can't contain the child-rule elements **CANNOTLOSEVALUE**, **NOTSAMEAS**, **MATCH**, and **PROHIBITEDVALUES**. -* Except for the following fields, **FIELD** definitions for System.*Name* fields can't contain field rules. - * System.Title can contain the rules **REQUIRED** and **DEFAULT**. - * System.Description can contain the rules **REQUIRED** and **DEFAULT**. - * System.AssignedTo can contain the rules **REQUIRED**, **DEFAULT**, **ALLOWEXISTINGVALUE**, and **VALIDUSER**. - * System.ChangedBy can contain the rules **REQUIRED**, **DEFAULT**, **ALLOWEXISTINGVALUE**, and **VALIDUSER**. +| Restriction | Details | +|-------------------|---------------------------| +| Field-rule elements can't specify the *for* and *not* attributes. | These attributes aren't allowed in field-rule elements.| +| `FIELD` elements can't contain the child-rule elements `CANNOTLOSEVALUE`, `NOTSAMEAS`, `MATCH`, and `PROHIBITEDVALUES`. | These child-rule elements aren't supported within `FIELD` elements. | +| `FIELD` definitions for `System.Name` fields can't contain field rules, except for specific fields. | Only certain fields can contain specific rules, as outlined in this article. | +| `System.Title` | Can contain the rules `REQUIRED` and `DEFAULT`. | +| `System.Description` | Can contain the rules `REQUIRED` and `DEFAULT`. | +| `System.AssignedTo` | Can contain the rules `REQUIRED`, `DEFAULT`, `ALLOWEXISTINGVALUE`, and `VALIDUSER`. | +| `System.ChangedBy` | Can contain the rules `REQUIRED`, `DEFAULT`, `ALLOWEXISTINGVALUE`, and `VALIDUSER`. | #### Consistent names and attributes -Within a process or a project collection, **name**, **type**, and other attributes that a **FIELD** element defines must be the same across all WIT definitions. +Within a process or a project collection, `name`, `type`, and other attributes that a `FIELD` element defines must be the same across all WIT definitions. @@ -273,23 +266,25 @@ Within a process or a project collection, **name**, **type**, and other attribut Identity fields correspond to fields used to contain account, user, or group names. The following core system fields are hard-coded as identity fields: -* Assigned To (System.AssignedTo) -* Authorized As (System.AuthorizedAs) -* Changed By (System.ChangedBy) -* Created By (System.CreatedBy) -* Activated By (Microsoft.VSTS.Common.ActivatedBy) -* Closed By (Microsoft.VSTS.Common.ClosedBy) -* Resolved By (Microsoft.VSTS.Common.ResolvedBy) +| Field Name | Reference Name | +|------------------|---------------------------------------------| +| Assigned To | `System.AssignedTo` | +| Authorized As | `System.AuthorizedAs` | +| Changed By | `System.ChangedBy` | +| Created By | `System.CreatedBy` | +| Activated By | `Microsoft.AzureDevOps.Common.ActivatedBy` | +| Closed By | `Microsoft.AzureDevOps.Common.ClosedBy` | +| Resolved By | `Microsoft.AzureDevOps.Common.ResolvedBy` | ##### Add a custom identity field -A string field is recognized as an identity field when you specify the attribute **syncnamechanges** as True. +A string field is recognized as an identity field when you specify the attribute `syncnamechanges` as True. ##### Rule restrictions on identity fields -For the current release of process import, don't specify any of the following rules within a **FIELD** definition. +For the current release of process import, don't specify any of the following rules within a `FIELD` definition. -* **SUGGESTEDVALUES** +* `SUGGESTEDVALUES` * Rules that contain nonidentity values. ##### Correct example @@ -304,7 +299,7 @@ To limit the account names that are valid within an identity field, specify the ``` -Before you import the process, make sure you've created the group in the projects that the process updates. +Before you import the process, make sure you created the group in the projects that the process updates. ##### Incorrect example @@ -329,12 +324,12 @@ The following example isn't valid because it specifies: ### Workflow -A **WORKFLOW** element and its child elements must conform to the syntax and rules described in [WORKFLOW XML element reference](/previous-versions/azure/devops/reference/xml/all-workflow-xml-elements-reference). Also, it must meet the following conditions: +A `WORKFLOW` element and its child elements must conform to the syntax and rules described in [WORKFLOW XML element reference](/previous-versions/azure/devops/reference/xml/all-workflow-xml-elements-reference). Also, it must meet the following conditions: * Limits each WIT to 16 workflow states -* Defines all workflow states that are mapped to metastates in the ProcessConfiguration definition file +* Defines all workflow states that are mapped to metastates in the ProcessConfiguration.xml definition file * Defines a transition between all workflow states mapped to the "Proposed" state category and workflow states mapped to the "InProgress" state category -* Defines a transition between all workflow states mapped to the "InProgress" state category and workflow states mapped to the "Complete" state category. +* Defines a transition between all workflow states mapped to the "InProgress" state category and workflow states mapped to the "Complete" state category For a description of state category and mappings, see [Workflow states and state categories](../../../../boards/work-items/workflow-and-state-categories.md). @@ -344,22 +339,21 @@ 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. -* Approximately 10,000 items can be defined in total among all global lists that are specified across all WITs. +* There are at most 64 global lists +* 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 ### Form layout -A **FORM** element and its child elements must conform to the syntax and rules described in [FORM XML element reference](/previous-versions/azure/devops/reference/xml/all-form-xml-elements-reference). +A `FORM` element and its child elements must conform to the syntax and rules described in [FORM XML element reference](/previous-versions/azure/devops/reference/xml/all-form-xml-elements-reference). -A **Control** element can't specify a custom control. Custom controls aren't supported. +A `Control` element can't specify a custom control. Custom controls aren't supported. ## Related articles -- [Import and export a Hosted XML process](import-process.md) -- [Rules and rule evaluation](../rule-reference.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) +- [Import and export Hosted XML processes](import-process.md) +- [Evaluate rules and rule behavior](../rule-reference.md) +- [Change projects from Hosted XML to inherited processes](../change-process-from-hosted-to-inherited.md) +- [Clone Hosted XML processes to inherited processes](../upgrade-hosted-to-inherited.md) diff --git a/docs/organizations/settings/work/import-process/differences.md b/docs/organizations/settings/work/import-process/differences.md deleted file mode 100644 index 0899abb2119..00000000000 --- a/docs/organizations/settings/work/import-process/differences.md +++ /dev/null @@ -1,84 +0,0 @@ ---- -title: Differences between process customizations -titleSuffix: Azure DevOps Services -description: Summary of what you can and can't customize in a process template to support customized work tracking in Azure DevOps Services. -ms.service: azure-devops-boards -ms.assetid: 2B500AEA-165C-428D-B580-C9C0A8D01635 -ms.topic: conceptual -ms.author: chcomley -author: chcomley -monikerRange: 'azure-devops' -ms.date: 03/20/2018 ---- - -# Process template customizations differences between Azure DevOps Services and TFS - -[!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 select XML definition files of a process template. This feature is only available for organizations that have been migrated to Azure DevOps Services using the [TFS 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 Inheritance 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). - -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. -* 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. - -> [!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. - -## Unsupported customizations and unreferenced plug-in files - -Any reference to the following objects in any of the XML definition files result in a validation error upon import. -* Custom controls on work item forms -* Custom link types -* Global workflow -* Team field support -* For and Not rules support -* Match rule support - -The following plug-ins and their associated files aren't used in defining a process, nor used to update existing projects. -However, they are used to create objects or artifacts when you create a new project. -* Classification -* Work item queries (defined using the WIQL syntax) -* Test Management -* Work items - -> [!NOTE] -> The WIQL length must not exceed 32K characters. The system won't allow you to create or run queries that exceed that length. - -The following plug-ins and their associated files are replaced by system defaults. -* Build -* Groups and Permissions -* Lab -* Version Control - -The following plug-ins and their associated files are ignored. -* Microsoft Project Mappings -* Reports -* Windows SharePoint Services - -Custom plug-ins aren't supported. - -## Object limits -When customizing a process template for import, limit the number of the objects you define as specified in [Work tracking object limits](../object-limits.md). - - - -## Related articles - -- [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 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..249258d3fb5 100644 --- a/docs/organizations/settings/work/upgrade-hosted-to-inherited.md +++ b/docs/organizations/settings/work/upgrade-hosted-to-inherited.md @@ -8,7 +8,7 @@ ms.author: chcomley author: chcomley ms.topic: how-to monikerRange: 'azure-devops' -ms.date: 05/30/2018 +ms.date: 04/30/2025 --- # Clone a Hosted XML process to an Inheritance process @@ -16,43 +16,34 @@ ms.date: 05/30/2018 [!INCLUDE [version-eq-azure-devops](../../../includes/version-eq-azure-devops.md)] Cloning your Hosted XML process to the Inheritance process model allows you to manage customizations through the user interface versus XML definition files. The inherited process supports the set of customizations described here [About process customization and inherited processes](inheritance-process-model.md). - -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. - - -## Sequence of steps - -The general sequence of steps to support clone are: -1. Open **Settings>Process** -1. Choose the Hosted XML process you want to clone and select **Clone process to inheritance** from its context menu -2. Verify the customizations that are present in the inherited process created as part of the clone -3. Manually reapply customizations that were ignored during clone -4. Create a test project to verify customizations. - -[!INCLUDE [temp](../includes/open-process-admin-context-ts-only.md)] +Before you clone a Hosted XML process, review the [supported operations when moving from Hosted XML process to inherited process](change-process-from-hosted-to-inherited.md#supported-operations-for-moving-from-hosted-xml-to-an-inherited-process). +[!INCLUDE [prerequisites-change-process](../includes/prerequisites-change-process.md)] ## Clone a Hosted XML process to an Inheritance process -1. Open the … context menu for the Hosted XML process and choose the **Clone process to inherited** option. +1. Sign in to your organization (```https://dev.azure.com/{Your_Organization}```). +2. Select ![gear icon](../../../media/icons/gear-icon.png) **Organization settings**. + + > [!div class="mx-imgBorder"] + > ![Screenshot showing highlighted Organization settings button.](../../../media/settings/open-admin-settings-vert.png) +3. Select **Process**. +2. Open the … context menu for the Hosted XML process and choose the **Clone process to inherited** option. Here we open the menu for the Design Agile Process. > [!div class="mx-imgBorder"] > ![Agile process context menu, Choose Clone process to inherited](media/migration/upgrade-to-inherited-option-menu.png) -1. Review the information provided in the dialog that opens and then choose **Continue**. +3. Review the information provided in the dialog that opens and then choose **Continue**. > [!div class="mx-imgBorder"] > ![Clone from XML to inheritance dialog information](media/migration/upgrade-from-xml-to-inheritance.png) -2. In the next dialog, you can change the name of the inherited process to be created and optionally change the parent process and provide a description. +4. In the next dialog, you can change the name of the inherited process to be created and optionally change the parent process and provide a description. Here, we accept the defaults provided by the system. @@ -60,35 +51,39 @@ The general sequence of steps to support clone are: > ![Accept the defaults provided by the system.](media/migration/upgrade-from-xml-to-inheritance-dialog.png) > [!IMPORTANT] - > The system performs a best effort to detect the correct parent process. Verify that the process selected meets your expectations, or change it as needed. Once you've completed the clone, you can't clone it a second time based on a different system process. + > The system performs a best effort to detect the correct parent process. Verify that the process selected meets your expectations, or change it as needed. Once you complete the clone, you can't clone it a second time based on a different system process. -3. After you've confirmed that the information is correct, choose **Save**. +5. After you confirm that the information is correct, select **Save**. [!INCLUDE [temp](../includes/post-upgrade-steps.md)] + ## Verify the customization you made -We recommend that you create a test project based on the inherited process created in the previous step to verify the customizations preserved and any additional changes you make to it. +Create a test project based on the inherited process created in the previous step to verify the customizations preserved and any other changes you make to it. 1. Open the **All processes** page, and choose the … context menu for the process you want to use, and then select **New project**. > [!div class="mx-imgBorder"] > ![Create a project from the selected process](media/migration/create-team-project-inherited-process.png) -1. The Create new project page opens. Fill out the form. +2. The Create new project page opens. Complete the form. > [!div class="mx-imgBorder"] > ![Create new project form](media/process/create-test-project.png) -2. Open the **Work>Work Items** page (user context) and choose **New Work Item** and select a WIT that you have previously customized. Here we choose **Bug**. +3. Open the **Work>Work Items** page (user context) and choose **New Work Item** and select a WIT that you previously customized. In the following example, we choose **Bug**. > [!div class="mx-imgBorder"] > ![Work, Work Items Page, Add New Work Item, Bug](media/process/add-custom-field-verify-bug.png) -3. Verify that the customizations you expect appear on the form. +4. Verify that the customizations you expect appear on the form. +5. Manually reapply customizations that were ignored during clone. +6. Create a test project to verify customizations. + +## Next steps -## Try this next > [!div class="nextstepaction"] > [Change a project from a Hosted XML process to Inheritance](change-process-from-hosted-to-inherited.md) @@ -96,4 +91,4 @@ We recommend that you create a test project based on the inherited process creat ### Q: Why are some of my fields missing on the form when I clone a Hosted XML process to Inherited? -During the cloning process we do our best to match your layout from Hosted XML and clone it into Inherited. However, if you have been creative with the form layout, we can't always replicate that same layout in Inherited. They system does a best attempt. Fields and layouts that are not understood get ignored. The fields however are still added to the process. You just need to manually add them to the form layout. +During the cloning process, the system makes a best effort to replicate your layout from Hosted XML into the Inherited process. However, it might not always be possible to fully replicate the same layout. Fields and layouts that aren't recognized are ignored during the cloning process, but the fields are still added to the process. You need to manually add these fields to the form layout as needed. diff --git a/docs/organizations/settings/work/upgrade-support-hosted-to-inherited.md b/docs/organizations/settings/work/upgrade-support-hosted-to-inherited.md deleted file mode 100644 index bf7d4e6e9f3..00000000000 --- a/docs/organizations/settings/work/upgrade-support-hosted-to-inherited.md +++ /dev/null @@ -1,74 +0,0 @@ ---- -title: Customizations when cloning a Hosted XML process -titleSuffix: Azure DevOps Services -description: Describes the set of customizations that are preserved versus those that are ignored when upgrading a Hosted XML process to Inheritance -ms.custom: inherited-process -ms.service: azure-devops-boards -ms.assetid: -ms.author: chcomley -author: chcomley -ms.topic: conceptual -monikerRange: 'azure-devops' -ms.date: 05/30/2018 ---- - - -# Supported operations when moving from Hosted XML to an inherited process - -[!INCLUDE [version-eq-azure-devops](../../../includes/version-eq-azure-devops.md)] - - - -Upgrading a Hosted XML process model to an inherited process provides the convenience of customizing your work tracking system through the user interface. For an overview of supported customizations available to you with the Inheritance process, see [About process customization and inherited processes](inheritance-process-model.md). - -While the clone process attempts to model all your work tracking customizations, there are some limitations. This article outlines the set of customizations that are supported during the clone process and those which aren't. - -The Inheritance process model supports most customizations, however some of the more advanced customizations you made with the Hosted XML process might not be supported. In addition, some of the customizations made to the Hosted XML process need to be manually created in the inherited process. - -> [!NOTE] -> Before you [change the process of an existing project](change-process-from-hosted-to-inherited.md) from Hosted XML to the cloned inherited process, review this article to understand which customizations are preserved and which are ignored. - -## Customizations preserved during clone - -When you clone a Hosted XML process to an inherited process, the customizations listed in the following table are preserved. - -> [!div class="mx-tdCol2BreakAll"] -> |Artifact      | Description | -> |------|---------| -> | 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). | -> | 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. | -> | Default properties | The default properties set for teams that you add to a project are preserved as documented in [Process configuration XML element reference, Specify properties and behaviors](../../../reference/xml/process-configuration-xml-element.md#specify-properties-and-behaviors). | - - -## Customizations ignored during clone - -> [!div class="mx-tdCol2BreakAll"] -> |Artifact      | Description | -> |------|---------| -> | Header area customization | Any customizations made to the header area within the work item form are ignored. The header area, as shown in the following image, is managed by the system. Any customizations made within the **SystemControls** section of the **WebLayout** are ignored.

      ![Work item web form, Header area](media/migration/header-area.png) | -> | Four column layout and size | The inherited process supports a [a fixed relative sizing of three columns](inheritance-process-model.md#resizing) to a WIT layout, while the Hosted XML process supports up to four columns and allows you to set the first column as equal sized with the rest of the columns. | -> | Hide Details page in layout | The inherited process ignores any customizations made to hide the Details page in a WIT layout. | -> | Workflow restriction | The inherited process follows an any-to-any workflow state transition. Any customizations that restrict the transition from one workflow state to another are ignored. | -> | Workflow state reasons | Customized reasons added to workflow states are ignored. | -> | Conditional picklists | Conditional picklists, also referred to as dependent or cascading picklists, are ignored. Multiple sets of allowed values per field are ignored. Picklists are defined for a field at the collection level and shared across processes and WITs. | -> | Custom rules | All custom rules to fields and workflow are ignored. | -> | Custom link controls | Custom link controls are ignored. | -> | 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. | - - -[!INCLUDE [temp](../includes/post-upgrade-steps.md)] - - -## Related articles - -- [About process customization and inherited processes](inheritance-process-model.md) -- [Clone a Hosted XML process to Inheritance](upgrade-hosted-to-inherited.md) -- [Change a project from a Hosted XML process to Inheritance](change-process-from-hosted-to-inherited.md) - diff --git a/docs/organizations/toc.yml b/docs/organizations/toc.yml index 3f35923b49c..1e6fd406e61 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 @@ -28,18 +25,9 @@ - name: Set personal favorites displayName: project, team, backlog, dashboard, view, query, repository, pipeline, test plan href: ../project/navigation/set-favorites.md?toc=/azure/devops/organizations/toc.json - - 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 - 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 + - name: Manage OAuth apps displayName: OAuth, services, access - href: ./settings/manage-authorizations.md + href: ./settings/manage-authorizations.md?toc=/azure/devops/organizations/toc.json - name: Organizations href: ../organizations/accounts/toc.yml - name: Projects @@ -138,14 +126,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..964306e4d8b 100644 --- a/docs/pipelines/.openpublishing.redirection.pipelines.json +++ b/docs/pipelines/.openpublishing.redirection.pipelines.json @@ -1,5 +1,17 @@ { "redirections": [ + { + "source_path": "docs/pipelines/agents/v2-osx-agent.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/agents/v2-osx-agent" + }, + { + "source_path": "docs/pipelines/agents/v2-linux-agent.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/agents/v2-linux-agent" + }, + { + "source_path": "docs/pipelines/agents/v2-windows-agent.md", + "redirect_url": "/previous-versions/azure/devops/pipelines/agents/v2-windows-agent" + }, { "source_path_from_root": "/docs/pipelines/get-started/multi-stage-pipelines-experience.md", "redirect_url": "/azure/devops/pipelines/create-first-pipeline", @@ -35,6 +47,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 +152,114 @@ { "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" + }, + { + "source_path_from_root": "/docs/pipelines/integrations/microsoft-teams.md", + "redirect_url": "/microsoftteams/m365-custom-connectors#update-connectors-url" } ] } 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..28dd0e616ef 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: 07/03/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" @@ -26,53 +25,76 @@ Microsoft-hosted agents are only available with Azure DevOps Services, which is ## Software -The **Azure Pipelines** agent pool offers several virtual machine images to choose from, each including a broad range of tools and software. +The **Azure Pipelines** agent pool offers several virtual machine images to choose from, each including a broad range of tools and software. You can see the installed software for each image by choosing the **Included Software** link in the following table. For more information on the software lifecycle and deprecation schedule of images and software, see [GitHub Actions Runner Images - Software and Image Support](https://github.com/actions/runner-images/tree/main?tab=readme-ov-file#software-and-image-support). + +#### [Windows images](#tab/windows-images/) + +You can see the installed software for each Windows hosted agent image by choosing the **Included Software** link in the table. | 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) | - -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). - - -### Recent updates - -* The macOS 13 image is 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). -* [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). -* [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. -* 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: - * Windows Server 2012R2 with Visual Studio 2015 (`vs2015-win2012r2`) - * macOS X High Sierra 10.13 (`macOS-10.13`) - * Windows Server Core 1803 (`win1803`) - -Customers are encouraged to migrate to newer versions or a [self-hosted agent](windows-agent.md). - -For more information and instructions on how to update your pipelines that use those images, see [Removing older images in Azure Pipelines hosted pools](https://devblogs.microsoft.com/devops/removing-older-images-in-azure-pipelines-hosted-pools/). +| Windows Server 2025 with Visual Studio 2022 | *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 - See [Windows Server 2019 hosted image deprecation schedule](#windows-server-2019-hosted-image-deprecation-schedule)| *windows-2019* | `windows-2019` | [Link](https://aka.ms/windows-2019-readme) | -> [!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 about this update, 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). +The **windows-2019** image is the default image for classic build pipelines. For more information, see [Designate a pool in your pipeline](pools-queues.md#designate-a-pool-in-your-pipeline). + +#### Windows image updates + +* [Windows Server 2025 with Visual Studio 2022 image is GA](https://aka.ms/azdo-windows) + * The `windows-latest` label still refers to `windows-2022`. The change to `windows-2025` will be made in the future and this page will be updated at that time. +* [[Windows & Ubuntu] .NET 6 will be removed from the images on 2025-08-01.](https://github.com/actions/runner-images/issues/12241) +* [Windows Server 2019 hosted image deprecation schedule](#windows-server-2019-hosted-image-deprecation-schedule) + +##### Windows Server 2019 hosted image deprecation schedule + +The Windows Server 2019 image is scheduled to be deprecated: +* Deprecation start date: June 1, 2025 +* Brownout period: June 3, 2025 to June 24, 2025 +* Scheduled removal date for Windows Server 2019 hosted image: December 31, 2025 + +For more information, see [Upcoming Updates for Azure Pipelines Agents Images - Windows](https://aka.ms/azdo-windows) + +#### [Linux images](#tab/linux-images/) + +You can see the installed software for each Linux hosted agent image by choosing the **Included Software** link in the table. + +| Image | Classic Editor Agent Specification | YAML VM Image Label | Included Software | +| --- | --- | --- | --- | +| Ubuntu 24.04 | *ubuntu-24.04* | `ubuntu-latest` 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) | + +The `ubuntu-latest` image is the default image for YAML pipelines if no image is specified. For more information, see [Designate a pool in your pipeline](pools-queues.md#designate-a-pool-in-your-pipeline). + +#### Linux images updates + +* [[Windows & Ubuntu] .NET 6 will be removed from the images on 2025-08-01.](https://github.com/actions/runner-images/issues/12241) +* 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`. +* [The Ubuntu 20.04 image is retired](https://devblogs.microsoft.com/devops/upcoming-updates-for-azure-pipelines-agents-images/#ubuntu). + +#### [macOS images](#tab/macos-images/) + +You can see the installed software for each macOS 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). + +| Image | Classic Editor Agent Specification | YAML VM Image Label | Included Software | +| --- | --- | --- | --- | +| 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) | + +#### macOS images updates + +* [[macOS] Xcode 15.4 will be removed from macOS15 images on May 29th, 2025](https://github.com/actions/runner-images/issues/12195) +* [The macOS-15 Sequoia image is available in preview](https://devblogs.microsoft.com/devops/upcoming-updates-for-azure-pipelines-agents-images/#mac-os) +* Apple silicon (ARM64) support for macOS image - for more information on joining the preview, see [Apple silicon (ARM64) support for macOS image](https://devblogs.microsoft.com/devops/upcoming-updates-for-azure-pipelines-agents-images/#mac-os). +* The macOS-12 Monterey image has been retired + +* * * > [!IMPORTANT] > To request additional software to be installed on Microsoft-hosted agents, don't create a feedback request on this document or open a support ticket. Instead, open an issue on our [repository](https://github.com/actions/runner-images), where we manage the scripts to generate various images. + ### How to identify pipelines using a deprecated hosted image To identify pipelines that are using a deprecated image, browse to the following location in your organization: `https://dev.azure.com/{organization}/{project}/_settings/agentqueues`, and filter on the image name to check. The following example checks the `vs2017-win2016` image. @@ -89,7 +111,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 +161,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 +210,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 +238,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 +268,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 +281,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 +324,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 +336,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 +346,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 +356,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 +376,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..b296f308006 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: 06/12/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://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..e6a980cdd96 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. @@ -35,7 +35,7 @@ For example, `VSTS_AGENT_INPUT_PASSWORD` instead of specifying `--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 +- `--replace` - Specify `--replace` if you are replacing the current agent installation with an agent with the same name. If your intention is to replace an agent with the same name that's hosted elsewhere, unconfigure the other agent first before configuring this one (and you don't need to specify `--replace`); otherwise if you have two agent instances with the same name, you'll get conflicts, and after a few moments of conflicts, one of the agents will shut down. ### Agent setup - `--work ` - work directory where job data is stored. Defaults to `_work` under the @@ -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..0f24310170b 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: 06/12/2025 --- ### How do I configure the agent to bypass a web proxy and connect to Azure Pipelines? @@ -30,7 +30,7 @@ https://dev.azure.com 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..91b02b1de7a 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: 06/12/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://download.agent.dev.azure.com` | Agent package | +> [!IMPORTANT] +> [Edgio CDN for Azure DevOps was 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..7ef3246fdd3 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: 06/12/2025 --- ### How do I configure the agent to bypass a web proxy and connect to Azure Pipelines? @@ -30,25 +30,42 @@ https://dev.azure.com 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..ee4db4d22dc --- /dev/null +++ b/docs/pipelines/agents/personal-access-token-agent-registration.md @@ -0,0 +1,78 @@ +--- +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' +ms.custom: sfi-image-nochange +--- + +# 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.](../../organizations/accounts/media/pats/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.](../../organizations/accounts/media/pats/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..89e52bf56f8 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: 06/12/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://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..ffd3e24b139 --- /dev/null +++ b/docs/pipelines/agents/service-principal-agent-registration.md @@ -0,0 +1,70 @@ +--- +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 + - sfi-image-nochange +--- + +# 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 deleted file mode 100644 index ade1a51c9ed..00000000000 --- a/docs/pipelines/agents/v2-linux-agent.md +++ /dev/null @@ -1,444 +0,0 @@ ---- -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.assetid: 834FFB19-DCC5-40EB-A3AD-18B7EDCA976E -ms.date: 05/05/2023 -monikerRange: '<= azure-devops' ---- - -# Self-hosted Linux agents (2.x) - -[!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] - -:::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 Linux agents](linux-agent.md). - -:::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. - -> 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. -> * Otherwise, you've come to the right place to set up an agent on Linux. Continue to the next section. - -[!INCLUDE [include](includes/concepts.md)] - -## Check prerequisites - -::: moniker range="> tfs-2018" - -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 - - openSUSE 42.3 or later - - Oracle Linux 8, 7 - - Red Hat Enterprise Linux 8, 7, 6 (see note 1) - - SUSE Enterprise Linux 12 SP2 or later - - Ubuntu 20.04, 18.04, 16.04 - - Azure Linux 1.0 (see note 3) -- ARM32 (see note 2) - - Debian 9 - - Ubuntu 18.04 -- ARM64 - - Debian 9 - - 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. - -> [!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/). - -> [!NOTE] -> Note 2: ARM instruction set [ARMv7](https://en.wikipedia.org/wiki/List_of_ARM_microarchitectures) or above is required. -> Run `uname -a` to see your Linux distro's instruction set. - -> [!NOTE] -> 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. -We strongly recommend installing the latest version of Git. - -> [!NOTE] -> The agent installer knows how to check for other dependencies. -You can install those dependencies on supported Linux platforms by running `./bin/installdependencies.sh` in the agent directory. -> -> Be aware that some of these dependencies required by .NET Core are fetched from third party sites, like `packages.efficios.com`. Review the `installdependencies.sh` script and ensure any referenced third party sites are accessible from your Linux machine before running the script. -> -> Please also make sure that all required repositories are connected to the relevant package manager used in `installdependencies.sh` (like `apt` or `zypper`). -> -> 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 - -If you're building from a Subversion repo, you must install the Subversion client on the machine. - -You should run agent setup manually the first time. -After you get a feel for how agents work, or if you want to automate setting up many agents, consider using [unattended config](#unattended-config). - -### 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. -(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. - -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 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. -2. Download TEE-CLC version 14.135.0 manually from [Team Explorer Everywhere GitHub releases](https://github.com/microsoft/team-explorer-everywhere/releases). -3. Extract the contents of `TEE-CLC-14.135.0` folder to `/externals/tee`. - -

      Prepare permissions

      - -[!INCLUDE [include](includes/v2/prepare-permissions.md)] - - -## Download and configure the agent - -::: moniker range="azure-devops" - -### Azure Pipelines - -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 Azure Pipelines, and navigate to the **Agent pools** tab: - - [!INCLUDE [include](includes/agent-pools-tab.md)] - -1. Select the **Default** pool, select the **Agents** tab, and choose **New agent**. - -1. On the **Get the 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. 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" - -### Azure DevOps Server 2019 and Azure DevOps Server 2020 - -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 Azure DevOps Server 2019, and navigate to the **Agent pools** tab: - - [!INCLUDE [include](includes/agent-pools-tab.md)] - -1. Click **Download agent**. - -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. 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" - -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)] - -## Run interactively - -For guidance on whether to run the agent in interactive mode or as a service, see [Agents: Interactive vs. service](agents.md#interactive-or-service). - -To run the agent interactively: - -1. If you have been running the agent as a service, [uninstall the service](#service_uninstall). - -1. Run the agent. - - ```bash - ./run.sh - ``` - - 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. - -### Run once - -For agents configured to run interactively, you can choose to have the agent accept only one job. -To run in this configuration: - - ```bash -./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). - -## Run as a systemd service - -If your agent is running on these operating systems you can run the agent as a `systemd` service: - -* Ubuntu 16 LTS or newer -* 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. -We encourage you to review, and if needed, update the script before running it. - -Some important caveats: -* If you run your agent as a service, you cannot run the agent service as `root` user. -* Users running [SELinux](https://selinuxproject.org/) have reported difficulties with the provided `svc.sh` script. -Refer to [this agent issue](https://github.com/microsoft/azure-pipelines-agent/issues/2738) as a starting point. -SELinux is not an officially supported configuration. - -> [!NOTE] -> If you have a different distribution, or if you prefer other approaches, you can use whatever kind of service mechanism you prefer. See [Service files](#service-files). - -### Commands - -#### Change to the agent directory - -For example, if you installed in the `myagent` subfolder of your home directory: - -```bash -cd ~/myagent$ -``` - -#### Install - -Command: - -```bash -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. - -#### Start - -```bash -sudo ./svc.sh start -``` - -#### Status - -```bash -sudo ./svc.sh status -``` - -#### Stop - -```bash -sudo ./svc.sh stop -``` - -

      Uninstall

      - -> You should stop before you uninstall. - -```bash -sudo ./svc.sh uninstall -``` - -

      Update environment variables

      - -When you configure the service, it takes a snapshot of some useful environment variables for your current logon user such as PATH, LANG, JAVA_HOME, ANT_HOME, and MYSQL_PATH. If you need to update the variables (for example, after installing some new software): - -```bash -./env.sh -sudo ./svc.sh stop -sudo ./svc.sh start -``` - -The snapshot of the environment variables is stored in `.env` file (`PATH` is stored in `.path`) under agent root directory, you can also change these files directly to apply environment variable changes. - -### Run instructions before the service starts - -You can also run your own instructions and commands to run when the service starts. For example, you could set up the environment or call scripts. - -1. Edit `runsvc.sh`. - -1. Replace the following line with your instructions: - - ```bash - # insert anything to setup env when running as a service - ``` - -

      Service files

      - -When you install the service, some service files are put in place. - -#### systemd service file - -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: - -* **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` - -* **TFS or Azure DevOps Server**: the name of your on-premises server. For example if you connect to `http://our-server:8080/tfs`, then the service name would be `/etc/systemd/system/vsts.agent.our-server.our-linux-agent.service` - -`sudo ./svc.sh install` generates this file from this template: `./bin/vsts.agent.service.template` - -#### .service file - -`sudo ./svc.sh start` finds the service by reading the `.service` file, which contains the name of systemd service file described above. - -### Alternative service mechanisms - -We provide the `./svc.sh` script as a convenient way for you to run and manage your agent as a systemd service. But you can use whatever kind of service mechanism you prefer (for example: initd or upstart). - -You can use the template described above as to facilitate generating other kinds of service files. - -## 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). - -[!INCLUDE [include](includes/v2/replace-agent.md)] - -[!INCLUDE [include](includes/v2/remove-and-reconfigure-unix.md)] - -[!INCLUDE [include](includes/v2/configure-help-unix.md)] - -[!INCLUDE [include](includes/capabilities.md)] - -## FAQ - -[!INCLUDE [include](includes/v3/qa-agent-version.md)] - - - -[!INCLUDE [include](includes/v2/qa-agent-version.md)] - -### Why is sudo needed to run the service commands? - -`./svc.sh` uses `systemctl`, which requires `sudo`. - -Source code: [systemd.svc.sh.template on GitHub](https://github.com/Microsoft/azure-pipelines-agent/blob/master/src/Misc/layoutbin/systemd.svc.sh.template) - -::: moniker range="azure-devops" - -[!INCLUDE [include](includes/v2/qa-firewall.md)] - -::: moniker-end - -### How do I run the agent with self-signed certificate? - -[Run the agent with self-signed certificate](certificate.md) - -### How do I run the agent behind a web proxy? - -[Run the agent behind a web proxy](proxy.md) - -### 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 systemd service, follow the steps to [Stop](#stop) and then [Start](#start) the agent. - -::: moniker range="azure-devops" - -[!INCLUDE [include](includes/v2/web-proxy-bypass.md)] - -::: moniker-end - -::: moniker range="azure-devops" - -[!INCLUDE [include](includes/v2/qa-urls.md)] - -::: moniker-end - -::: moniker range="< azure-devops" - -[!INCLUDE [include](../includes/qa-versions.md)] - -::: moniker-end - - diff --git a/docs/pipelines/agents/v2-osx-agent.md b/docs/pipelines/agents/v2-osx-agent.md deleted file mode 100644 index 40468bf9c23..00000000000 --- a/docs/pipelines/agents/v2-osx-agent.md +++ /dev/null @@ -1,430 +0,0 @@ ---- -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 -ms.date: 05/05/2023 -monikerRange: '<= azure-devops' ---- - -# Self-hosted macOS agents (2.x) - -[!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] - -:::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 macOS agents](osx-agent.md). - -:::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. - -> 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. -> * Otherwise, you've come to the right place to set up an agent on macOS. Continue to the next section. - -[!INCLUDE [include](includes/concepts.md)] - -## Check prerequisites - -::: moniker range=">= tfs-2018" - -Make sure your machine has these prerequisites: -- macOS 10.15 "Catalina", macOS 11.0 "Big Sur", or macOS 12.0 "Monterey" -- Git 2.9.0 or higher (latest version strongly recommended - you can easily install with [Homebrew](https://brew.sh/)) - -These prereqs are required for agent version 2.125.0 and higher. - -::: moniker-end - -### 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. -(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. - -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 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. -2. Download TEE-CLC version 14.135.0 manually from [Team Explorer Everywhere GitHub releases](https://github.com/microsoft/team-explorer-everywhere/releases). -3. Extract the contents of `TEE-CLC-14.135.0` folder to `/externals/tee`. - -

      Prepare permissions

      - -If you're building from a Subversion repo, you must install the Subversion client on the machine. - -You should run agent setup manually the first time. -After you get a feel for how agents work, or if you want to automate setting up many agents, consider using [unattended config](#unattended-config). - -[!INCLUDE [permissions](includes/v2/prepare-permissions.md)] - - -## Download and configure the agent - -::: moniker range="azure-devops" - -### Azure Pipelines - -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 Azure Pipelines, and navigate to the **Agent pools** tab: - - [!INCLUDE [include](includes/agent-pools-tab.md)] - -1. Select the **Default** pool, select the **Agents** tab, and choose **New agent**. - -1. On the **Get the agent** dialog box, click **macOS**. - -1. Click the **Download** button. - -1. Follow the instructions on the page. - -1. Clear the extended attribute on the tar file: `xattr -c vsts-agent-osx-x64-V.v.v.tar.gz`. - -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 - -::: moniker range=">= azure-devops-2019 < azure-devops" - -### Azure DevOps Server 2019 and Azure DevOps Server 2020 - -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 Azure DevOps Server, and navigate to the **Agent pools** tab: - - [!INCLUDE [include](includes/agent-pools-tab.md)] - -1. Click **Download agent**. - -1. On the **Get agent** dialog box, click **macOS**. - -1. Click the **Download** button. - -1. Follow the instructions on the page. - -1. Clear the extended attribute on the tar file: `xattr -c vsts-agent-osx-x64-V.v.v.tar.gz`. - -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 - -::: 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 Azure Pipelines or 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 **macOS**. - -1. Click the **Download** button. - -1. Follow the instructions on the page. - -1. Clear the extended attribute on the tar file: `xattr -c vsts-agent-osx-x64-V.v.v.tar.gz`. - -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" - -Azure Pipelines: `https://dev.azure.com/{your-organization}` - -::: moniker-end - -::: moniker range="< azure-devops" - -TFS 2018 and newer: `https://{your_server}/tfs` - -::: moniker-end - -### Authentication type - -[!INCLUDE [include](includes/v2/unix-authentication-types.md)] - -## Run interactively - -For guidance on whether to run the agent in interactive mode or as a service, see [Agents: Interactive vs. service](agents.md#interactive-or-service). - -To run the agent interactively: - -1. If you have been running the agent as a service, [uninstall the service](#service_uninstall). - -1. Run the agent. - - ```bash - ./run.sh - ``` - - 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. - -### Run once - -For agents configured to run interactively, you can choose to have the agent accept only one job. To run in this configuration: - - ```bash -./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). - -## 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. - -> [!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: - -* `{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: - -* 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` - -* TFS: the name of your on-premises TFS AT server. For example if you connect to `http://our-server:8080/tfs`, then the service name would be `vsts.agent.our-server.our-osx-agent` - -### Commands - -#### Change to the agent directory - -For example, if you installed in the `myagent` subfolder of your home directory: - -```bash -cd ~/myagent$ -``` - - -#### Install - -Command: - -```bash -./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. - - -#### Start - -Command: - -```bash -./svc.sh start -``` - -Output: - -```bash -starting vsts.agent.{tfs-name}.{agent-name} -status vsts.agent.{tfs-name}.{agent-name}: - -/Users/{your-name}/Library/LaunchAgents/vsts.agent.{tfs-name}.{agent-name}.plist - -Started: -13472 0 vsts.agent.{tfs-name}.{agent-name} -``` - -The left number is the pid if the service is running. If second number is not zero, then a problem occurred. - -#### Status - -Command: -```bash -./svc.sh status -``` - -Output: - -```bash -status vsts.agent.{tfs-name}.{agent-name}: - -/Users/{your-name}/Library/LaunchAgents/vsts.{tfs-name}.{agent-name}.testsvc.plist - -Started: -13472 0 vsts.agent.{tfs-name}.{agent-name} -``` - -The left number is the pid if the service is running. If second number is not zero, then a problem occurred. - -#### Stop - -Command: - -```bash -./svc.sh stop -``` - -Output: - -```bash -stopping vsts.agent.{tfs-name}.{agent-name} -status vsts.agent.{tfs-name}.{agent-name}: - -/Users/{your-name}/Library/LaunchAgents/vsts.{tfs-name}.{agent-name}.testsvc.plist - -Stopped -``` - -

      Uninstall

      - -> You should stop before you uninstall. - -Command: - -```bash -./svc.sh uninstall -``` - -#### Automatic login and lock - -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). - -

      Update environment variables

      - -When you configure the service, it takes a snapshot of some useful environment variables for your current logon user such as PATH, LANG, JAVA_HOME, ANT_HOME, and MYSQL_PATH. If you need to update the variables (for example, after installing some new software): - -```bash -./env.sh -./svc.sh stop -./svc.sh start -``` - -The snapshot of the environment variables is stored in `.env` file under agent root directory, you can also change that file directly to apply environment variable changes. - -### Run instructions before the service starts - -You can also run your own instructions and commands to run when the service starts. For example, you could set up the environment or call scripts. - -1. Edit `runsvc.sh`. - -1. Replace the following line with your instructions: - - ```bash - # insert anything to setup env when running as a service - ``` - -

      Service Files

      - -When you install the service, some service files are put in place. - -#### .plist service file - -A .plist service file is created: - -``` -~/Library/LaunchAgents/vsts.agent.{tfs-name}.{agent-name}.plist -``` - -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` - -#### .service file - -`./svc.sh start` finds the service by reading the `.service` file, which contains the path to the plist service file described above. - -### 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. - -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). - -[!INCLUDE [include](includes/v2/replace-agent.md)] - -[!INCLUDE [include](includes/v2/remove-and-reconfigure-unix.md)] - -[!INCLUDE [include](includes/v2/configure-help-unix.md)] - -[!INCLUDE [include](includes/capabilities.md)] - -## FAQ - -[!INCLUDE [include](includes/v3/qa-agent-version.md)] - - - -[!INCLUDE [include](includes/v2/qa-agent-version.md)] - -### Where can I learn more about how the launchd service works? - -[Apple Developer Library: Creating Launch Daemons and Agents](https://developer.apple.com/library/archive/documentation/macOSX/Conceptual/BPSystemStartup/Chapters/CreatingLaunchdJobs.html) - -::: moniker range="azure-devops" - -[!INCLUDE [include](includes/v2/qa-firewall.md)] - -::: moniker-end - -### How do I run the agent with self-signed certificate? - -[Run the agent with self-signed certificate](certificate.md) - -### How do I run the agent behind a web proxy? - -[Run the agent behind a web proxy](proxy.md) - -### 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, follow the steps to [Stop](#stop) and then [Start](#start) the agent. - -::: moniker range="azure-devops" - -[!INCLUDE [include](includes/v2/web-proxy-bypass.md)] - -::: moniker-end - -::: moniker range="azure-devops" - -[!INCLUDE [include](includes/v2/qa-urls.md)] - -::: moniker-end - -::: moniker range="< azure-devops" - -[!INCLUDE [include](../includes/qa-versions.md)] - -::: moniker-end - - diff --git a/docs/pipelines/agents/v2-windows-agent.md b/docs/pipelines/agents/v2-windows-agent.md deleted file mode 100644 index 1f089bc4dfc..00000000000 --- a/docs/pipelines/agents/v2-windows-agent.md +++ /dev/null @@ -1,346 +0,0 @@ ---- -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) -ms.topic: conceptual -ms.assetid: 20409B8F-A3A9-49A0-A418-1840BD7ADA8E -ms.date: 05/05/2023 -monikerRange: '<= azure-devops' ---- - -# Self-hosted Windows agents (2.x) - -[!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] - -:::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). - -:::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. - -> 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)] - -## Check prerequisites - -Make sure your machine has these prerequisites: -- Windows 7 SP1 [ESU](/troubleshoot/windows-client/windows-7-eos-faq/windows-7-extended-security-updates-faq), 8.1, 10, or 11 (if using a client OS) -- Windows 2012 or higher (if using a server OS) -- [PowerShell 3.0](/powershell/scripting/install/installing-windows-powershell) or higher -- [.NET Framework](/dotnet/framework/install/) 4.6.2 or higher - -> [!IMPORTANT] -> Starting December 2019, the minimum required .NET version for build agents is 4.6.2 or higher. - -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. -After you get a feel for how agents work, or if you want to automate setting up many agents, consider using [unattended config](#unattended-config). - -### 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. -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. - -

      Prepare permissions

      - -[!INCLUDE [permissions](includes/v2/prepare-permissions.md)] - - -## Download and configure the agent - -::: moniker range="azure-devops" - -### Azure Pipelines - -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 Azure Pipelines, and navigate to the **Agent pools** tab: - - [!INCLUDE [include](includes/agent-pools-tab.md)] - -1. Select the **Default** pool, select the **Agents** tab, and choose **New agent**. - -1. On the **Get the agent** dialog box, choose **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. -If you aren't sure which version of Windows is installed, [follow these instructions to find out](/windows/client-management/windows-version-search). - -1. On the right pane, 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`. This will ask you a series of questions to configure the agent. - -::: moniker-end - -::: moniker range=">= azure-devops-2019 < azure-devops" - -### Azure DevOps Server 2019 and Azure DevOps Server 2020 - -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 Azure DevOps Server 2019, and navigate to the **Agent pools** tab: - - [!INCLUDE [include](includes/agent-pools-tab.md)] - -1. Click **Download agent**. - -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. -If you aren't sure which version of Windows is installed, [follow these instructions to find out](/windows/client-management/windows-version-search). - -1. On the right pane, 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`. This will ask you a series of questions to configure the agent. - -::: 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**. -> -> You must not use [Windows PowerShell ISE](/powershell/scripting/windows-powershell/ise/introducing-the-windows-powershell-ise) to configure the agent. - -> [!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. - -### Server URL and authentication - -::: 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="< azure-devops" -When setup asks for your server URL, for TFS, answer `https://{your_server}/tfs`. -::: moniker-end - -::: moniker range="azure-devops" -When setup asks for your authentication type, choose **PAT**. -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 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: - -* **Alternate** Connect to TFS using Basic authentication. After you select Alternate you'll be 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. - -* **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. - -> [!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). - -::: moniker-end - -### Choose interactive or service mode - -For guidance on whether to run the agent in interactive mode or as a service, see [Agents: Interactive vs. service](agents.md#interactive-or-service). - -If you choose to run as a service (which we recommend), the username you run as should be 20 characters or fewer. - -## Run the agent - -### Run interactively - -If you configured the agent to run interactively, to run it: - - ```ps - .\run.cmd - ``` - -To restart the agent, press Ctrl+C to stop the agent and then run `run.cmd` to restart it. - -### Run once - -For agents configured to run interactively, you can choose to have the agent accept only one job. -To run in this configuration: - - ```ps - .\run.cmd --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). - -### 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*)". - -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. - -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/v2/replace-agent.md)] - -## Remove and re-configure an agent - -To remove the agent: - -```ps -.\config remove -``` - -After you've removed the agent, you can [configure it again](#download-configure). - -## Unattended config - -The agent can be set up from a script with no human intervention. -You must pass `--unattended` and then answers to all questions. - -[!INCLUDE [unattend](./includes/v2/unattended-config.md)] - -`.\config --help` always lists the latest required and optional responses. - -## Diagnostics - -If you're having trouble with your self-hosted agent, you can try running diagnostics. -After configuring the agent: - -```ps -.\run --diagnostics -``` - -This will run through a diagnostic suite that may help you troubleshoot the problem. -The diagnostics feature is available starting with version 2.165.0. - -## Help on other options - -To learn about other options: - -```ps -.\config --help -``` - -The help provides information on authentication alternatives and unattended configuration. - -[!INCLUDE [include](includes/capabilities.md)] - -## FAQ - -[!INCLUDE [include](includes/v3/qa-agent-version.md)] - - - -[!INCLUDE [include](includes/v2/qa-agent-version.md)] - -::: moniker range="azure-devops" -[!INCLUDE [include](includes/v2/qa-firewall.md)] -::: moniker-end - -### How do I run the agent with self-signed certificate? - -[Run the agent with self-signed certificate](certificate.md) - -### How do I run the agent behind a web proxy? - -[Run the agent behind a web proxy](proxy.md) - -### 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). - -::: moniker range="azure-devops" -### How do I set different environment variables for each individual agent? - -Create a `.env` file under agent's root directory and put environment variables you want to set into the file as following format: - -``` -MyEnv0=MyEnvValue0 -MyEnv1=MyEnvValue1 -MyEnv2=MyEnvValue2 -MyEnv3=MyEnvValue3 -MyEnv4=MyEnvValue4 -``` -::: moniker-end - -::: moniker range="azure-devops" -[!INCLUDE [include](includes/v2/web-proxy-bypass.md)] -::: moniker-end - -::: moniker range="azure-devops" -[!INCLUDE [include](includes/v2/qa-urls.md)] -::: moniker-end - -::: moniker range="< azure-devops" -[!INCLUDE [include](../includes/qa-versions.md)] -::: moniker-end - -### What is enable SERVICE_SID_TYPE_UNRESTRICTED for agent service? - -When configuring the agent software on Windows Server, you can specify the service security identifier from the following prompt. - -``` -Enter enable SERVICE_SID_TYPE_UNRESTRICTED for agent service (Y/N) (press enter for N) -``` - -Previous versions of the agent software set the service security identifier type to `SERVICE_SID_TYPE_NONE`, which is the default value for the current agent versions. To configure the security service identifier type to `SERVICE_SID_TYPE_UNRESTRICTED`, press `Y`. - -For more information, see [SERVICE_SID_INFO structure](/windows/win32/api/winsvc/ns-winsvc-service_sid_info) and [Security identifiers](/windows-server/identity/ad-ds/manage/understand-security-identifiers). - - diff --git a/docs/pipelines/agents/v3-agent.md b/docs/pipelines/agents/v3-agent.md index 3a417e553fd..dcdc0865f82 100644 --- a/docs/pipelines/agents/v3-agent.md +++ b/docs/pipelines/agents/v3-agent.md @@ -1,15 +1,28 @@ --- 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: 06/30/2025 --- # Agent software version 3 +> [!IMPORTANT] +> Agent software version 3 (using .NET 6) is unsupported for Azure DevOps Services, and the Azure Pipelines team recommends you upgrade to [Agent software version 4](./v4-agent.md) (using .NET 8). +> +> To update your self-hosted agents to version 4, see [Upgrade to agent software version 4](./v4-agent.md#upgrade-to-4x-agent-on-supported-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). For more information, see [Upgrade to agent software version 4 on unsupported operating systems](./v4-agent.md#upgrade-to-4x-agent-on-unsupported-operating-systems). + 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 +31,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 +39,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 +74,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 +130,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..37741dd932b --- /dev/null +++ b/docs/pipelines/agents/v4-agent.md @@ -0,0 +1,150 @@ +--- +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: 06/30/2025 +--- + +# 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. + +To manually initiate the update, see [Update self-hosted agents](./agents.md#to-update-self-hosted-agents). + +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). After updating, see [Update self-hosted agents](./agents.md#to-update-self-hosted-agents) for instructions on how to update your agents to the 4.x version. + +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..fbd0134e9b3 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@3 task to run tests. The sample repository doesn't contain tests, so you can remove the VSTest@3 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..d7d0d2469f7 100644 --- a/docs/pipelines/apps/cd/deploy-docker-webapp.md +++ b/docs/pipelines/apps/cd/deploy-docker-webapp.md @@ -1,37 +1,38 @@ --- -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: 05/14/2025 monikerRange: '<= azure-devops' +ms.custom: sfi-image-nochange "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'll 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 -> - Deploy to deployment slots +> - Build and publish a Docker image to Azure Container Registry. +> - Create an Azure Web App. +> - Deploy a container to Azure App Service. +> - Deploy to deployment slots. ## 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 DevOps organization. [Create an organization](../../../organizations/accounts/create-organization.md), if you don't have one already. -- An Azure Container Registry. [Create an Azure container registry](/azure/container-registry/container-registry-get-started-portal#create-a-container-registry) if you don't have one already. +| **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.| +| **Azure** | - An Azure Container Registry. [Create an Azure container registry](/azure/container-registry/container-registry-get-started-portal#create-a-container-registry) if you don't have one already.| ## 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) @@ -67,15 +68,15 @@ To complete this section successfully, you must have an [Azure Container Registr 1. Select the **Docker: build and push an image to Azure Container Registry** pipeline template. - :::image type="content" source="media/docker-template.png" alt-text="Select Docker pipeline template"::: + :::image type="content" source="media/docker-template.png" alt-text="Screenshot of selecting the Docker pipeline template."::: 1. Select your Azure subscription, and then select **Continue**. 1. Select your **Container registry** from the drop-down menu, and then select **Validate and configure**. - :::image type="content" source="media/validate-and-configure.png" alt-text="Validate and configure Docker"::: + :::image type="content" source="media/validate-and-configure.png" alt-text="Screenshot of the Validate and Configure Docker screen."::: -1. Review the pipeline YAML template, and then select **Save and run** to build and publish the Docker image to your Azure Container Registry. +1. Review the pipeline YAML template, then select **Save and run** to build and publish the Docker image to Azure Container Registry. ```YAML trigger: @@ -114,31 +115,27 @@ To complete this section successfully, you must have an [Azure Container Registr tags: | $(tag) ``` -1. To view the published Docker image after your pipeline run has been completed, navigate to your container registry in Azure portal, and then select **Repositories**. +1. To view the published Docker image after the pipeline run is complete, go to the container registry in Azure portal, then select **Repositories**. - :::image type="content" source="media/docker-image-in-azure-portal.png" alt-text="Docker image published to Azure Container Registry"::: + :::image type="content" source="media/docker-image-in-azure-portal.png" alt-text="Screenshot of the Docker image published to Azure Container Registry."::: -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**. +1. To deploy the image from the container registry, enable the admin user account. Go to the container registry in Azure portal, and select **Access keys**. Then, 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 -## Create a Web App for Containers +1. Go to [Azure portal](https://portal.azure.com). -1. Navigate to [Azure portal](https://portal.azure.com). +1. Select **Create a resource** > **Containers**, then choose **Web App for Containers**. -1. Select **Create a resource** > **Containers**, and then choose **Web App for Containers**. + :::image type="content" source="media/create-web-app-container.png" alt-text="Screenshot of creating a web app for containers resource."::: - :::image type="content" source="media/create-web-app-container.png" alt-text="Create a web app for containers resource"::: +1. Enter a name for your new web app and create a new resource group. Select **Linux** for the **Operating System**. -1. Enter a name for your new web app, and create a new Resource Group. Select **Linux** for the **Operating System**. + :::image type="content" source="media/configure-web-app.png" alt-text="Screenshot of configuring the web app."::: - :::image type="content" source="media/configure-web-app.png" alt-text="Configure the web app"::: +1. In the **Pricing plans** section, select the **F1 Free plan**. -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. Select **Review and create**. Review your configuration, and select **Create** when you are done. +1. Select **Review and create**. Review your configuration and select **Create** when you're done. ## Deploy to Web App for Containers @@ -192,7 +189,7 @@ stages: inputs: azureSubscription: $(azureSubscription) appName: $(appName) - imageName: $(containerRegistry)/$(imageRepository):$(tag) + containers: $(containerRegistry)/$(imageRepository):$(tag) ``` # [Classic](#tab/classic/) @@ -203,38 +200,38 @@ stages: 1. Select the **Azure App Service deployment** template - :::image type="content" source="media/app-service-template.png" alt-text="Azure App Service template"::: + :::image type="content" source="media/app-service-template.png" alt-text="Screenshot of Azure App Service template."::: 1. Select **Tasks**, then **Unlink all** in **stage 1** to unlink all the pipeline parameters. - :::image type="content" source="media/unlink-parameters.png" alt-text="Unlink pipeline parameters"::: + :::image type="content" source="media/unlink-parameters.png" alt-text="Screenshot of unlink pipeline parameters."::: -1. Select the **Deploy Azure App Service** task, and fill out the required fields. Select **Save** when you are done. +1. Select the **Deploy Azure App Service** task, and fill out the required fields. Select **Save** when you're done. - :::image type="content" source="media/deploy-task.png" alt-text="Deploy Azure App Service task"::: + :::image type="content" source="media/deploy-task.png" alt-text="Screenshot of deploy Azure App Service task."::: -1. Select **Create release**, and then choose **Stage 1** from the dropdown menu. Select **Create** when you are done. +1. Select **Create release**, and then choose **Stage 1** from the dropdown menu. Select **Create** when you're done. - :::image type="content" source="media/create-release.png" alt-text="Create a release pipeline"::: + :::image type="content" source="media/create-release.png" alt-text="Screenshot of create a release pipeline."::: -1. Hover over **Stage 1** in your pipeline, and select **Deploy** to queue and start the deployment. +1. Hover over **Stage 1** in your pipeline, and then select **Deploy** to queue and start the deployment. - :::image type="content" source="media/deploy-docker-image.png" alt-text="Queue and deploy Docker image"::: + :::image type="content" source="media/deploy-docker-image.png" alt-text="Screenshot of queue and deploy Docker image."::: -1. Your pipeline logs should look similar to the screenshot below. +1. Your pipeline logs should look similar to this screenshot. - :::image type="content" source="media/pipeline-logs.png" lightbox="media/pipeline-logs.png" alt-text="Pipeline logs"::: + :::image type="content" source="media/pipeline-logs.png" lightbox="media/pipeline-logs.png" alt-text="Screenshot of pipeline logs."::: 1. Navigate to your newly deployed web app to verify your deployment. - :::image type="content" source="media/deployed-web-app.png" alt-text="Web app deployed. Hello World message"::: + :::image type="content" source="media/deployed-web-app.png" alt-text="Screenshot of web app deployed. Hello World message."::: --- ## Deploy to a deployment slot # [YAML](#tab/yaml/) -You can configure the Azure Web App container to have multiple slots. Slots allow you to safely deploy your app and test it before making it available to your customers. See [Create staging environments](/azure/app-service/deploy-staging-slots) for more details. +Configure the Azure Web App container to have multiple slots. Slots let you safely deploy your app and test it before making it available to your customers. Learn more in [Create staging environments](/azure/app-service/deploy-staging-slots). The following YAML snippet shows how to deploy to a staging slot, and then swap to a production slot: @@ -243,7 +240,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 @@ -260,7 +257,7 @@ The following YAML snippet shows how to deploy to a staging slot, and then swap # [Classic](#tab/classic/) You can configure the Azure Web App for container to have multiple slots. Slots allow you to safely deploy your app and test it before making it available to your customers. -Use the option **Deploy to Slot** in the **Azure Web App Container** task to specify the slot to deploy to. You can swap the slots by using the **Azure App Service Manage** task. +Use the **Deploy to Slot** option in the **Azure Web App Container** task to specify the slot to deploy to. Swap the slots by using the **Azure App Service Manage** task. *** @@ -268,12 +265,12 @@ Use the option **Deploy to Slot** in the **Azure Web App Container** task to spe ### Q: How can I find my Docker registry credentials? -A: Navigate to [Azure portal](https://portal.azure.com), and then select your Web App for Containers. Select **Configuration** > **Application settings** and then click to show the value. +A: Go to [Azure portal](https://portal.azure.com), and select your Web App for Containers. Select **Configuration** > **Application settings**, and then select to show the value. -[ ![A screenshot showing how to find Docker registry credentials.](azure/media/configure-app-service-security.png) ](azure/media/configure-app-service-security.png#lightbox) +[ ![Screenshot of the Azure portal showing how to find Docker registry credentials.](azure/media/configure-app-service-security.png) ](azure/media/configure-app-service-security.png#lightbox) ## Related articles - [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..8fb51e30cb7 100644 --- a/docs/pipelines/apps/mobile/app-signing.md +++ b/docs/pipelines/apps/mobile/app-signing.md @@ -1,260 +1,291 @@ --- -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' +ms.custom: sfi-image-nochange --- -# 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..1934cfc7c99 100644 --- a/docs/pipelines/artifacts/artifacts-overview.md +++ b/docs/pipelines/artifacts/artifacts-overview.md @@ -1,70 +1,111 @@ --- 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 -monikerRange: '<= azure-devops' +ms.date: 12/05/2023 +monikerRange: '>= azure-devops-2020' "recommendations": "true" --- # Artifacts in Azure Pipelines - overview -[!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] +[!INCLUDE [version-gt-eq-2020](../../includes/version-gt-eq-2020.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..8273d75f518 100644 --- a/docs/pipelines/artifacts/build-artifacts.md +++ b/docs/pipelines/artifacts/build-artifacts.md @@ -1,16 +1,15 @@ --- 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' +monikerRange: '>= azure-devops-2020' --- -# Artifacts in Azure Pipelines +# Publish and download build artifacts -[!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] +[!INCLUDE [version-gt-eq-2020](../../includes/version-gt-eq-2020.md)] ::: moniker range="azure-devops" @@ -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..31460f5134d --- /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-2020' +"recommendations": "true" +--- + +# Build and publish pipeline artifacts with Gradle and Azure Pipelines + +[!INCLUDE [version-gt-eq-2020](../../includes/version-gt-eq-2020.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..9a02d9e1ac2 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 -monikerRange: '<= azure-devops' +ms.date: 11/14/2024 +monikerRange: '>= azure-devops-2020' "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)] +[!INCLUDE [version-gt-eq-2020](../../includes/version-gt-eq-2020.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-a-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..97eb91f3934 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)] +[!INCLUDE [version-gt-eq-2020](../../includes/version-gt-eq-2020.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-a-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..ee2281c557a 100644 --- a/docs/pipelines/artifacts/publish-maven-artifacts.md +++ b/docs/pipelines/artifacts/publish-maven-artifacts.md @@ -1,110 +1,168 @@ --- -title: Publish Maven artifacts -description: How to publish Maven artifacts with Azure Pipelines -ms.topic: conceptual -ms.date: 10/24/2022 -monikerRange: '<= azure-devops' +title: Publish Maven artifacts with Azure Pipelines +description: Learn how to publish Maven artifacts to internal and external feed using Azure Pipelines. +ms.topic: how-to +ms.date: 06/30/2025 +monikerRange: '>= azure-devops-2020' --- -# 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. +[!INCLUDE [version-gt-eq-2020](../../includes/version-gt-eq-2020.md)] -## Set up your project +Azure Pipelines enables developers to publish Maven artifacts to Azure Artifacts feeds within the same organization, across other organizations, and to public registries such as Maven Central. This article guides you through publishing your Maven artifacts using both YAML and Classic pipelines. -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. +## Prerequisites - ```XML - - MavenDemo - https://pkgs.dev.azure.com/ORGANIZATION-NAME/PROJECT-NAME/_packaging/FEED-NAME/maven/v1 - - true - - - true - - +| **Product** | **Requirements** | +|--------------------|--------------------| +| **Azure DevOps** | - An Azure DevOps [organization](../../organizations/accounts/create-organization.md) and a [project](../../organizations/projects/create-project.md).
      - An Azure Artifacts [feed](../../artifacts/start-using-azure-artifacts.md#create-a-new-feed).
      - A [working pipeline](../create-first-pipeline.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). | + +## Publish packages to 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: 'Authenticate to Azure Artifacts feed' + inputs: + artifactsFeeds: 'MavenDemo,MavenDemoFeed2' ## Select one or multiple feeds to authenticate with. + - script: | + mvn deploy + displayName: 'Publish' ``` -1. Configure your *settings.xml* file as follows. Replace the placeholders with your organization name, your project name, and your personal access token. +#### [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**: 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 are assigned 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 a different organization - ```XML - - PROJECT-NAME - ORGANIZATION-NAME - PERSONAL-ACCESS-TOKEN - +To publish packages to a feed in a different Azure DevOps organization, you must first create a personal access token (PAT) in the target organization, and then use that PAT to create a service connection and authenticate with the target feed. + +#### Create a personal access token + +1. Navigate to the organization that hosts the target feed. + +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 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. For **Authentication method**, select **Username and Password**. Enter your **Repository URL** and your **Repository Id**. + +1. In the **Username** field, enter any string value (this is required, but Azure Pipelines will use your `pom.xml` configuration and the personal access token you created earlier for authentication). + - For **Password**, paste the personal access token you created earlier. + - Provide a **Name** for your service connection. + - 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: + MavenServiceConnections: + + - script: | + mvn deploy + displayName: 'Publish' ``` -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. +#### [Classic](#tab/classic/) + +::: moniker range="azure-devops" -## Build your code +1. Sign in to your Azure DevOps organization, and then navigate to your project. -In this example, we're using the [Maven task](../tasks/build/maven.md) to build the project with Azure Pipelines. +::: moniker-end -```yml -- task: Maven@3 - 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' -``` +::: moniker range="< azure-devops" -## Publish packages to your pipeline +1. Sign in to your Azure DevOps collection, and then navigate to your project. -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-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" -:::image type="content" source="media/published-maven-pipeline.png" alt-text="A screenshot showing the build artifact published to drop in Azure Pipelines."::: +2. Select **Pipelines**, and then select your pipeline definition. -## Publish packages to your feed +::: moniker-end -To publish your package to an Azure Artifacts feed, use the Maven task to deploy your artifact to your feed. +3. Select **Edit**, and then select the `+` icon to add a new task. Add the **Maven Authenticate** and **Command line** tasks to your pipeline definition and configure them as follows: -```yml -- task: Maven@3 - 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' -``` + 1. **Maven Authenticate**: From the **Credentials for repositories outside this organization/collection** dropdown, select your service connection. -:::image type="content" source="media/maven-published-to-feed.png" alt-text="A screenshot showing the build artifact published to a feed."::: + 1. **Command line task**: + - **Display name**: Publish. + - **Script**: `mvn deploy` -## Q&A +4. Select **Save & queue** when you're done. -#### Q: How to authenticate with MavenAuthenticate? +- - - -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: +## Related content -- [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) +- [Maven Authenticate v0 task](/azure/devops/pipelines/tasks/reference/maven-authenticate-v0) -## Related articles +- [Use the .artifactignore file](../../artifacts/reference/artifactignore.md) -- [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 +- [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..f367230c89b 100644 --- a/docs/pipelines/artifacts/publish-public-registry.md +++ b/docs/pipelines/artifacts/publish-public-registry.md @@ -1,32 +1,29 @@ --- -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.topic: conceptual -ms.date: 05/14/2023 -monikerRange: '<= azure-devops' +ms.date: 12/23/2024 +monikerRange: '>= azure-devops-2020' +ms.custom: + - peer-review-program + - sfi-image-nochange "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 +31,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..4a839a610cc 100644 --- a/docs/pipelines/artifacts/symbols.md +++ b/docs/pipelines/artifacts/symbols.md @@ -1,94 +1,130 @@ --- -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 -monikerRange: '<= azure-devops' +ms.date: 09/22/2023 +monikerRange: '>= azure-devops-2020' "recommendations": "true" --- -# Publish symbols for debugging +# Publish symbols with Azure Pipelines -[!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] +[!INCLUDE [version-gt-eq-2020](../../includes/version-gt-eq-2020.md)] With Azure Pipelines, you can publish your symbols to Azure Artifacts symbol server using the *Index sources and publish symbols* task. You can use the debugger to connect and automatically retrieve the correct symbol files without knowing product names, build numbers, or package names. Using Azure Pipelines, you can also publish your symbols to files shares and portable PDBs. > [!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..0cd6ca4731a --- /dev/null +++ b/docs/pipelines/build/build-tag.md @@ -0,0 +1,130 @@ +--- +title: Add, remove, and use build tags +description: Learn how to add, remove, and use build tags. +ms.topic: how-to +ms.date: 05/12/2025 +ms.custom: template-how-to-pattern +ai-usage: ai-assisted +ms.author: jukullam +author: juliakm +monikerRange: '>= azure-devops-2020' +--- + +# Add, remove, and use build tags + +[!INCLUDE [version-gt-eq-2020](../../includes/version-gt-eq-2020.md)] + +Build tags in Azure DevOps help you categorize and organize your builds, making it easier to filter and locate specific builds. This guide walks you through adding, removing, and using build tags as part of your build management process. + +## Prerequisites + +An Azure DevOps organization and access to a project where you're a member of the **Contributors** group. + +## Add a build tag to a completed build + +#### [Azure Pipelines UI](#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 (for 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 tag. + +#### [Azure DevOps CLI](#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 automatically add a build tag to a future 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 is 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've 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 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 filters the builds based on the specified tag, letting you 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..048a599e394 100644 --- a/docs/pipelines/customize-pipeline.md +++ b/docs/pipelines/customize-pipeline.md @@ -1,21 +1,21 @@ --- 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: 06/09/2025 +monikerRange: "<=azure-devops" --- # Customize your pipeline [!INCLUDE [version-gt-eq-2019](../includes/version-gt-eq-2019.md)] -This is a step-by-step guide on common ways to customize your pipeline. +This article is a step-by-step guide on common ways to customize your pipeline. ## Prerequisite @@ -25,10 +25,10 @@ Follow instructions in [Create your first pipeline](create-first-pipeline.md) to A pipeline is defined using a YAML file in your repo. Usually, this file is named `azure-pipelines.yml` and is located at the root of your repo. -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. +Go to the **Pipelines** page in Azure Pipelines, select the pipeline you created, and select **Edit** in the context menu of the pipeline to open the YAML editor. > [!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. @@ -56,7 +56,7 @@ Examine the contents of the YAML file. > The contents of your YAML file may be different depending on the sample repo you started with, or upgrades made in Azure Pipelines. -This pipeline runs whenever your team pushes a change to the main branch of your repo or creates a pull request. It runs on a Microsoft-hosted Linux machine. The pipeline process has a single step, which is to run the Maven task. +The pipeline runs whenever your team pushes a change to the main branch of the repo or creates a pull request. It runs on a Microsoft-hosted Linux machine. The pipeline process has a single step, which is to run the Maven task. ## Change the platform to build on @@ -71,7 +71,7 @@ You can build your project on [Microsoft-hosted agents](../pipelines/agents/host vmImage: "ubuntu-latest" ``` -* To choose a different platform like Windows or Mac, change the `vmImage` value: +* To switch to a different platform like Windows or Mac, change the `vmImage` value: ```yaml pool: @@ -94,12 +94,11 @@ You can add more **scripts** or **tasks** as steps to your pipeline. A task is a * Add the following snippet to the end of your YAML file. ```yaml - - task: PublishCodeCoverageResults@1 + - task: PublishCodeCoverageResults@2 inputs: - codeCoverageTool: "JaCoCo" - summaryFileLocation: "$(System.DefaultWorkingDirectory)/**/site/jacoco/jacoco.xml" - reportDirectory: "$(System.DefaultWorkingDirectory)/**/site/jacoco" - failIfCoverageEmpty: true + summaryFileLocation: "$(System.DefaultWorkingDirectory)/**/site/jacoco/jacoco.xml" # Path to summary files + reportDirectory: "$(System.DefaultWorkingDirectory)/**/site/jacoco" # Path to report directory + failIfCoverageEmpty: true # Fail if code coverage results are missing ``` * Select **Save** and then confirm the changes. @@ -247,15 +246,14 @@ 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. +* **Automatically link work items included in this run** - The changes associated with a given pipeline run might 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. :::image type="content" source="media/customize-pipeline/link-work-items.png" alt-text="Screenshot of setting to automatically link work items included in this run."::: * 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,9 +261,12 @@ 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 -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. +::: 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 +313,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..1963185dd9b 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,98 +67,92 @@ 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 `apksignerKeystorePassword` and `apksignerKeyPassword` in [secret variables](../process/variables.md#secret-variables) and use those variables in your pipeline. ```yaml -- task: AndroidSigning@2 +- task: AndroidSigning@3 inputs: - apkFiles: '**/*.apk' - jarsign: true - jarsignerKeystoreFile: 'pathToYourKeystoreFile' - jarsignerKeystorePassword: '$(jarsignerKeystorePassword)' - jarsignerKeystoreAlias: 'yourKeystoreAlias' - jarsignerKeyPassword: '$(jarsignerKeyPassword)' - zipalign: true + apkFiles: '**/*.apk' # Specify the APK files to sign + apksignerKeystoreFile: 'pathToYourKeystoreFile' # Path to the keystore file + apksignerKeystorePassword: '$(apksignerKeystorePassword)' # Use a secret variable for security + apksignerKeystoreAlias: 'yourKeystoreAlias' # Alias for the keystore + apksignerKeyPassword: '$(apksignerKeyPassword)' # Use a secret variable for security + apksignerVersion: 'latest' # Use the latest version of apksigner + apksignerArguments: '--verbose' # Optional: Additional arguments for apksigner + zipalign: true # Enable zipalign to optimize APK + zipalignVersion: 'latest' # Use the latest version of zipalign ``` -::: 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 +160,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 +199,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 +212,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 +224,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 +237,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..feae4dd9f6d 100644 --- a/docs/pipelines/ecosystems/containers/build-image.md +++ b/docs/pipelines/ecosystems/containers/build-image.md @@ -2,38 +2,48 @@ 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: 05/13/2025 +monikerRange: '>=azure-devops-2020' --- # Quickstart: Build a container image to deploy apps using Azure Pipelines [!INCLUDE [version-eq-azure-devops](../../../includes/version-eq-azure-devops.md)] -This quickstart shows how to build a container image for app deployment using Azure Pipelines. To build this image, all you need is a Dockerfile in your repository. You can build Linux or Windows containers, based on the agent that you use in your pipeline. +In this quickstart, you learn to build a container image for app deployment using Azure Pipelines. To build this image, you only need a Dockerfile in your repository. You can build Linux or Windows containers depending on the agent you use in your pipeline. ## 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 -1. Sign in to your Azure DevOps organization, and go to your project. -1. Go to **Pipelines**, and select **New Pipeline**. +::: 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** 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**. - 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. Replace the contents of **azure-pipelines.yml** with the following code. Based on whether you're deploying a Linux or Windows app, make sure to respectively set `vmImage` to either `ubuntu-latest` or `windows-latest`. +1. Replace the contents of **azure-pipelines.yml** with the following code. Depending on whether you're deploying a Linux or Windows app, set `vmImage` to either `ubuntu-latest` or `windows-latest`. ```yaml trigger: @@ -56,13 +66,64 @@ 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, ensure 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. 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. +If you don't plan to keep using this application, delete your pipeline and code repository. ## FAQ @@ -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 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 save time 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 or daemon running on the agent's host. If Docker isn't installed, add the [Docker installer task](/azure/devops/pipelines/tasks/reference/docker-installer-v0) to your pipeline. 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 use 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. @@ -133,7 +193,7 @@ If you're using self-hosted agents, you can cache Docker layers without any work When you use Microsoft-hosted Linux agents, you create Linux container images for the x64 architecture. To create images for other architectures, such as x86 or ARM processor, you can use a machine emulator such as [QEMU](https://www.qemu.org/). -The following steps show how to create an ARM processor container image by using QEMU: +Follow these steps to create an ARM processor container image using QEMU: 1. Author your Dockerfile with a base image that matches the target architecture: @@ -153,11 +213,11 @@ For more information, see [qemu-user-static](https://github.com/multiarch/qemu-u ### How do I run tests and publish test results for containerized applications? -For different options on testing containerized applications and publishing the resulting test results, see [Publish Test Results task](../../tasks/test/publish-test-results.md#docker). +To explore options for testing containerized applications and publishing test results, see [Publish Test Results task](../../tasks/test/publish-test-results.md#docker). ## Next steps -After you build your container image, push the image to Azure Container Registry, Docker Hub, or Google Container registry. To learn how to push an image to a container registry, continue to either of the following articles: +After you build your container image, push the image to Azure Container Registry, Docker Hub, or Google Container registry. To learn how to push an image to a container registry, see either of the following articles: > [!div class="nextstepaction"] > [Push an image to Azure Container Registry](acr-template.md) diff --git a/docs/pipelines/ecosystems/containers/content-trust.md b/docs/pipelines/ecosystems/containers/content-trust.md index bdfd839f2ca..af0b0bc188b 100644 --- a/docs/pipelines/ecosystems/containers/content-trust.md +++ b/docs/pipelines/ecosystems/containers/content-trust.md @@ -3,40 +3,40 @@ 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.date: 02/11/2022 +ms.author: ericvan +author: geekzter +ms.date: 05/21/2025 monikerRange: 'azure-devops' --- # Docker Content Trust [!INCLUDE [version-eq-azure-devops](../../../includes/version-eq-azure-devops.md)] -Docker Content Trust (DCT) lets you use digital signatures for data sent to and received from remote Docker registries. These signatures allow client-side or runtime verification of the integrity and publisher of specific image tags. +Docker Content Trust (DCT) lets you use digital signatures for data sent to and received from remote Docker registries. These signatures let you verify the integrity and publisher of specific image tags on the client side or at runtime. > [!NOTE] -> A prerequisite for signing an image is a Docker Registry with a Notary server attached (examples include [Docker Hub](https://docs.docker.com/engine/security/trust/content_trust/) or [Azure Container Registry](/azure/container-registry/container-registry-content-trust)) +> To sign an image, you need a Docker Registry with an attached Notary server (examples include [Docker Hub](https://docs.docker.com/engine/security/trust/content_trust/) or [Azure Container Registry](/azure/container-registry/container-registry-content-trust)). ## Signing images in Azure Pipelines -### Prerequisites on development machine +### Prerequisites on the development machine -1. Use Docker trust's built-in generator or manually generate delegation key pair. If the [built-in generator](https://docs.docker.com/engine/security/trust/trust_delegation/#using-docker-trust-to-generate-keys) is used, the delegation private key is imported into the local Docker trust store. Else, the private key will need to be manually imported into the local Docker trust store. See [Manually Generating Keys](https://docs.docker.com/engine/security/trust/trust_delegation/#manually-generating-keys) for details. -1. Using the delegation key generated from the step above, upload the first key to a delegation and [initiate the repository](https://docs.docker.com/engine/security/trust/trust_delegation/#initiating-the-repository) +1. Use Docker trust's built-in generator or manually generate delegation key pair. If the [built-in generator](https://docs.docker.com/engine/security/trust/trust_delegation/#using-docker-trust-to-generate-keys) is used, the delegation private key is imported into the local Docker trust store. Otherwise, you need to manually import the private key into the local Docker trust store. See [Manually Generating Keys](https://docs.docker.com/engine/security/trust/trust_delegation/#manually-generating-keys) for details. +1. Use the delegation key generated in the previous step to upload the first key to a delegation and [initiate the repository](https://docs.docker.com/engine/security/trust/trust_delegation/#initiating-the-repository). > [!Tip] > To view the list of local Delegation keys, use the Notary CLI to run the following command: `$ notary key list`. ### Set up pipeline for signing images -1. Grab the delegation private key, which is in the local Docker trust store of your development machine used earlier, and add the same as a [secure file](../../library/secure-files.md) in Pipelines. +1. Get the delegation private key from the local Docker trust store on your development machine, and add it as a [secure file](../../library/secure-files.md) in Pipelines. 2. [Authorize this secure file](../../library/secure-files.md#secure-file-authorization) for use in all pipelines. 3. The service principal associated with `containerRegistryServiceConnection` must have the AcrImageSigner role in the target container registry. 4. Create a pipeline based on the following YAML snippet: ```yaml pool: - vmImage: 'Ubuntu 16.04' + vmImage: 'ubuntu-latest' variables: system.debug: true @@ -66,18 +66,19 @@ Docker Content Trust (DCT) lets you use digital signatures for data sent to and repository: $(imageRepository) tags: | $(tag) - arguments: '--disable-content-trust=false' - - task: Docker@2 - inputs: - command: push - containerRegistry: $(containerRegistryServiceConnection) - repository: $(imageRepository) - tags: | - $(tag) - arguments: '--disable-content-trust=false' - env: - DOCKER_CONTENT_TRUST_REPOSITORY_PASSPHRASE: $(DOCKER_CONTENT_TRUST_REPOSITORY_PASSPHRASE) + - task: Docker@2 + inputs: + command: push + containerRegistry: $(containerRegistryServiceConnection) + repository: $(imageRepository) + tags: | + $(tag) + env: + DOCKER_CONTENT_TRUST_REPOSITORY_PASSPHRASE: $(DOCKER_CONTENT_TRUST_REPOSITORY_PASSPHRASE) + DOCKER_CONTENT_TRUST_ROOT_PASSPHRASE: $(rootPassphrase) ``` - In the previous example, the `DOCKER_CONFIG` variable is set by the `login` command in the Docker task. We recommend that you set up `DOCKER_CONTENT_TRUST_REPOSITORY_PASSPHRASE` as a [secret variable](../../process/variables.md#secret-variables) for your pipeline. The alternative approach of using a pipeline variable in YAML exposes the passphrase in plain text. `DOCKER_CONTENT_TRUST_REPOSITORY_PASSPHRASE` in this example refers to the private key's passphrase (not the repository passphrase). We only need the private key's passphrase in this example because the repository has been initiated already (prerequisites). + In the previous example, the `DOCKER_CONFIG` variable is set by the `login` command in the Docker task. Set up `DOCKER_CONTENT_TRUST_REPOSITORY_PASSPHRASE` and `DOCKER_CONTENT_TRUST_ROOT_PASSPHRASE` as [secret variables](../../process/variables.md#secret-variables) for your pipeline. + + `DOCKER_CONTENT_TRUST_REPOSITORY_PASSPHRASE` in this example refers to the private key's passphrase (not the repository passphrase). We only need the private key's passphrase in this example because the repository has been initiated already (prerequisites). diff --git a/docs/pipelines/ecosystems/containers/publish-to-acr.md b/docs/pipelines/ecosystems/containers/publish-to-acr.md index c40a360afc6..7a4041cb552 100644 --- a/docs/pipelines/ecosystems/containers/publish-to-acr.md +++ b/docs/pipelines/ecosystems/containers/publish-to-acr.md @@ -4,12 +4,15 @@ 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' +ms.custom: sfi-image-nochange --- # 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 +30,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 +146,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 +228,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 +256,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..11e001fb674 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: 06/09/2025 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 Python apps without setting 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,16 +196,16 @@ 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. +Authenticate with `twine` by using 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 +- task: TwineAuthenticate@1 inputs: artifactFeed: '' 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..1b5cbe82ced 100644 --- a/docs/pipelines/ecosystems/ecosystems.md +++ b/docs/pipelines/ecosystems/ecosystems.md @@ -8,302 +8,53 @@ ms.manager: mijacobs ms.author: sdanie author: steved0x ms.custom: freshness-fy22q2 -ms.date: 12/22/2021 -featureFlags: -- clicktale +ms.date: 06/27/2025 monikerRange: '<= azure-devops' --- -# Create your Azure Pipelines ecosystem +# Azure Pipelines ecosystem examples [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -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" +The articles in this section provide examples of how to build and deploy applications using Azure Pipelines. ## Build your app -Build your app with any of the following languages. - -::: moniker-end - -::: moniker range=">= azure-devops-2019" - -:::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_anaconda.png"::: - [Anaconda](anaconda.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::: -:::row-end::: - -:::row::: - :::column::: - :::image type="icon" source="./media/index/logo_Cplusplus.png"::: - [C/C++ with GCC](../apps/c-cpp/gcc.md) - :::column-end::: - :::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::: -:::row-end::: - -:::row::: - :::column::: - :::image type="icon" source="./media/index/logo_java.png"::: - [Java](java.md) - :::column-end::: - :::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::: -:::row-end::: - -:::row::: - :::column::: - :::image type="icon" source="./media/index/logo_ruby.png"::: - [Ruby](ruby.md) - :::column-end::: - :::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::: -:::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" +See the following topics for examples of building your app with the following languages. + +- .NET + - [.NET Core](./dotnet-core.md) + - [.NET Framework](../apps/aspnet/build-aspnet-4.md) +- JavaScript + - [JavaScript quickstart](./javascript.md) + - [Customize JavaScript](./customize-javascript.md) + - [Node.js tutorial](./nodejs-tutorial.md) +- Python + - [Python quickstart](./python.md) + - [Customize Python](./customize-python.md) + - [Python to web app](./python-webapp.md) + - [Anaconda](./anaconda.md) +- Java + - [Java apps](./java.md) + - [Java to web App](./java-webapp.md) + - [Java to web app with MicroProfile](/azure/java/microprofile/cicd-microprofile) +- [Android](./android.md) +- [Go](./go.md) +- [PHP](./php.md) +- [Ruby](./ruby.md) +- [Xcode](./xcode.md) ## Deploy your app -Deploy your app to any of the following platforms. - -::: moniker-end - -::: moniker range=">= azure-devops-2019" - -:::row::: - :::column::: - :::image type="icon" source="./media/index/logo_kubernetes.png"::: - [Kubernetes](./kubernetes/deploy.md) - :::column-end::: - :::column::: - :::image type="icon" source="./media/index/azure-stack.png"::: - [Azure Stack](../targets/azure-stack.md) - :::column-end::: - :::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::: -:::row-end::: - -:::row::: - :::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::: - :::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::: -:::row-end::: - -:::row::: - :::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::: - :::column::: - :::image type="icon" source="./media/index/virtualmachine.png"::: - [Windows VM](../apps/cd/deploy-webdeploy-iis-deploygroups.md) - :::column-end::: - :::column::: - :::column-end::: -:::row-end::: - -::: 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 +See the following topics for information on deploying your app to any of the following platforms. + +- [Deploy to Azure services](../overview-azure.md) +- [Kubernetes](./kubernetes/deploy.md) +- [Azure Stack](../targets/azure-stack.md) +- [Azure SQL database](../targets/azure-sqldb.md) +- [Azure Web Apps](../targets/webapp.md) +- [npm](../artifacts/npm.md) +- [NuGet](../artifacts/nuget.md) +- [Virtual machine resources](../process/environments-virtual-machines.md) +- [Web App for Containers](../apps/cd/deploy-docker-webapp.md) +- [Deploy to Azure Functions](/azure/azure-functions/functions-how-to-azure-devops) 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..519f3082365 100644 --- a/docs/pipelines/ecosystems/java.md +++ b/docs/pipelines/ecosystems/java.md @@ -2,99 +2,102 @@ 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.custom: freshness-fy22q2, devdivchpfy22, devx-track-extended-java, ai-assisted ms.topic: quickstart -ms.date: 10/03/2022 -monikerRange: '<= azure-devops' +ms.date: 05/14/2025 +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 +Use Azure Pipelines to automate the build, test, and deployment of Java applications. This article explains how to set up a pipeline for Java projects using tools like Maven, Gradle, or Ant. You also learn how to deploy your app to Azure services like App Service, Functions, or Kubernetes. -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). +Use a pipeline to: -## Prerequisites +* Build your project with [Maven](https://maven.apache.org/), [Gradle](https://gradle.org/), or [Ant](https://ant.apache.org/). +* Run tests and code analysis tools. +* Publish your app using a 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 must have the following items in Azure DevOps: +If you work on an Android projects, see [Build, test, and deploy Android apps](android.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. +## Prerequisites -### Create a pipeline +[!INCLUDE [ecosystems-prerequisites](includes/ecosystems-prerequisites.md)] -::: moniker range="> azure-devops-2019" +## Create a GitHub repository -1. Fork the following repo at GitHub: +Fork the following repository to your GitHub account: - ``` - https://github.com/MicrosoftDocs/pipelines-java - ``` +```text +https://github.com/MicrosoftDocs/pipelines-java +``` -1. Sign in to your Azure DevOps organization and go to your project. +## Create a pipeline -1. Go to **Pipelines**, and then select **New pipeline**. +::: moniker range=">= azure-devops" -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. Sign in to your Azure DevOps organization, and go to your project. -1. Select your repo. You might be redirected to GitHub to install the Azure Pipelines app. If so, select **Approve & install**. +1. Go to **Pipelines**, and then select **New pipeline** or **Create pipeline** if creating the first pipeline in the project. -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. Follow the wizard steps, starting by 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. When you're ready, select **Save and run**. +1. Select your repository. You might be redirected to GitHub to install the Azure Pipelines app. If so, select **Approve & install** to proceed. -1. Commit a new _azure-pipelines.yml_ file to your repo. Select **Save and run** again. +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). - If you want to watch your pipeline in action, select the build job. +1. An `azure-pipelines.yml` file containing your pipeline definition is created in your repository 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). - 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. +1. When you're finished editing the `azure-pipelines.yml`, select **Save and run**. - You now have a working YAML pipeline (`azure-pipelines.yml`) in your repo that's ready for you to customize! +1. To commit the `azure-pipelines.yml` file to your repo, select **Save and run** again. -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. +Select **Job** to watch your pipeline in action. ::: moniker-end -::: moniker range="azure-devops-2019" +::: moniker range="< azure-devops" -1. Import the following repo into your Git repo in Azure DevOps Server 2019: +1. Go to your collection and select your project. - ``` - https://github.com/MicrosoftDocs/pipelines-java - ``` +1. Select **Pipelines**, and then select **New pipeline** or **Create pipeline** if creating the first pipeline in the project. -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 +1. Perform the steps of the wizard by first selecting **GitHub Enterprise Server** as the location of your source code. -::: moniker range="< azure-devops-2019" +1. Use an existing GitHub service connection or create a new one. -1. Import the following repo into your Git repo in TFS: + To create a service connection: - ``` - https://github.com/MicrosoftDocs/pipelines-java - ``` + 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). - This template automatically adds the tasks you need to build the code in the sample repo. +1. Select your repository. You might be redirected to GitHub to install the Azure Pipelines app. If so, select **Approve & install**. -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! +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. An `azure-pipelines.yml` file containing your pipeline definition is created in your repository 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. When you're finished editing the `azure-pipelines.yml`, select **Save and run**. + +1. To commit the `azure-pipelines.yml` file to your repo, select **Save and run** again. + + 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 repository 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). +Use Azure Pipelines to build Java apps without setting up infrastructure. Build on Windows, Linux, or macOS images. Microsoft-hosted agents in Azure Pipelines have modern JDKs and other tools for Java preinstalled. To check 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. +Select the appropriate image by updating the following snippet in your `azure-pipelines.yml` file. ```yaml pool: @@ -103,23 +106,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 Microsoft-hosted agents, set up [self-hosted agents](../agents/agents.md#install) with Java installed. Use self-hosted agents to save time if you have a large repo or 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. +Builds run on a [self-hosted agent](../agents/agents.md#install). Ensure Java and the tools required for your chosen build method are 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, specify the agent pool and an agent with the Maven capability by adding 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. +For a Maven build, add the following tasks to the `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,64 +141,64 @@ 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 -Adjust the `mavenPomFile` value if your `pom.xml` file isn't in the root of the repo. The file path value should be relative to the root of the repo, such as `IdentityService/pom.xml` or `$(system.defaultWorkingDirectory)/IdentityService/pom.xml`. +Set the `mavenPomFile` value if the `pom.xml` file isn't in the root of the repo. The file path value must be relative to the root of the repo, such as `IdentityService/pom.xml` or `$(system.defaultWorkingDirectory)/IdentityService/pom.xml`. #### 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. +For a Gradle build, add the following task to the `azure-pipelines.yml` file. For more information about these options, see the [Gradle](/azure/devops/pipelines/tasks/reference/gradle-v3) task. ```yaml steps: -- task: Gradle@2 +- task: Gradle@3 inputs: workingDirectory: '' gradleWrapperFile: 'gradlew' gradleOptions: '-Xmx3072m' javaHomeOption: 'JDKVersion' - jdkVersionOption: '1.8' + jdkVersionOption: 'default' jdkArchitectureOption: 'x64' publishJUnitResults: true testResultsFiles: '**/TEST-*.xml' tasks: 'build' ``` +#### Gradle wrapper + +Ensure the `gradlew` file is in the repo. If it isn't, generate it by running `gradle wrapper` in the 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 -Adjust the `workingDirectory` value if your `gradlew` file isn't in the root of the repo. +Set the `workingDirectory` value if the `gradlew` file isn't in the root of the repo. The directory value should be relative to the root of the repo, such as `IdentityService` or `$(system.defaultWorkingDirectory)/IdentityService`. Adjust the `gradleWrapperFile` value if your `gradlew` file isn't in the root of the repo. The file path value should be relative to the root of the repo, such as `IdentityService/gradlew` or `$(system.defaultWorkingDirectory)/IdentityService/gradlew`. #### 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 +207,7 @@ steps: workingDirectory: '' buildFile: 'build.xml' javaHomeOption: 'JDKVersion' - jdkVersionOption: '1.8' + jdkVersionOption: 'default' jdkArchitectureOption: 'x64' publishJUnitResults: false testResultsFiles: '**/TEST-*.xml' @@ -202,11 +215,11 @@ steps: ### Script -To build with a command line or script, add one of the following snippets to your `azure-pipelines.yml` file. +To build with a command line or script, add one of these snippets to the `azure-pipelines.yml` file. #### Inline script -The `script:` step runs an inline script using Bash on Linux and macOS and Command Prompt on Windows. For details, see the [Bash](/azure/devops/pipelines/tasks/reference/bash-v3) or [Command line](/azure/devops/pipelines/tasks/reference/cmd-line-v2) task. +The `script:` step runs an inline script using Bash on Linux and macOS, and Command Prompt on Windows. For details, see the [Bash](/azure/devops/pipelines/tasks/reference/bash-v3) or [Command line](/azure/devops/pipelines/tasks/reference/cmd-line-v2) task. ```yaml steps: @@ -218,7 +231,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 +242,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 +Publish your build output to your pipeline. Package and publish your app in a Maven package or a _.war/jar_ file to deploy it 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..7190fe00704 100644 --- a/docs/pipelines/ecosystems/javascript.md +++ b/docs/pipelines/ecosystems/javascript.md @@ -1,188 +1,164 @@ --- -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.topic: how-to +ms.custom: devx-track-js, freshness-fy22q2 +ms.date: 05/27/2025 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. +You can build, test, and deploy Node.js apps as part of your Azure Pipelines continuous integration and continuous delivery (CI/CD) system. Learn how to use a pipeline to create a Node.js package with Node Package Manager (npm) and publish a pipeline artifact. -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" +The example pipeline automates the process of building, testing, and packaging a Node.js application, making it ready for further deployment or distribution. ## 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. - -1. When the list of repositories appears, select your Node.js sample repository. - -1. Azure Pipelines analyzes the code in your repository and recommends the `Node.js` template for your pipeline. Select that template. - -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. +[!INCLUDE [ecosystems-prerequisites](includes/ecosystems-prerequisites.md)] -1. A new run starts. Wait for the run to finish. +## Fork the sample code -When you're done, you have a working YAML file *azure-pipelines.yml* in your repository that's ready for you to customize. +Fork the sample Express.js server app. -::: moniker-end - -::: moniker range="azure-devops-2019" - -1. [Create a pipeline](../create-first-pipeline.md) and select the **YAML** template. +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 give it a different name. -1. Set the **Agent pool** and **YAML file path** for your pipeline. +>[!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 instructions on the screen to complete the process. For more information, see [Access to GitHub repositories](../repos/github.md#access-to-github-repositories). -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. +## Create your pipeline -::: moniker-end +### [YAML](#tab/yaml) -::: moniker range=">=azure-devops-2020" +1. In your Azure DevOps project, select **Pipelines** > **Create Pipeline**, 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 named *azure-pipelines.yml* for your pipeline. +1. Select the dropdown caret next to **Save and run**, select **Save**, then select **Save** again. The file is saved to your forked GitHub repository. +1. On the next screen, select **Edit**. -## 3 - Build your package and publish an artifact +## Build the package and publish an artifact -1. **Edit** your *azure-pipelines.yml* file. +Edit the *azure-pipelines.yml* file as follows. -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 file contents with the following code. ```yaml trigger: - - main + - main pool: vmImage: 'ubuntu-latest' + variables: + nodeVersion: '18.x' + steps: - - task: NodeTool@0 - inputs: - versionSpec: '16.x' - displayName: 'Install Node.js' + # Install Node.js + - task: UseNode@1 + inputs: + version: $(nodeVersion) + displayName: 'Install Node.js' - - script: | - npm install - displayName: 'npm install' + # Install dependencies + - script: | + npm install + displayName: 'Install dependencies' - - script: | - npm run build - displayName: 'npm build' - ``` - -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. - - ```yaml - - task: CopyFiles@2 - inputs: - sourceFolder: '$(Build.SourcesDirectory)' - contents: | - src/* - public/* - targetFolder: '$(Build.ArtifactStagingDirectory)' - displayName: 'Copy project files' + # Build the project + - script: | + npm run build + displayName: 'Build project' - - task: PublishPipelineArtifact@1 - inputs: - artifactName: e2e-server - targetPath: '$(Build.ArtifactStagingDirectory)' - publishLocation: 'pipeline' - displayName: 'Publish npm artifact' + # Run tests + - script: | + npm test + displayName: 'Run tests' + + # Copy project files to artifact staging directory + - task: CopyFiles@2 + inputs: + sourceFolder: '$(Build.SourcesDirectory)' + contents: | + src/** + public/** + targetFolder: '$(Build.ArtifactStagingDirectory)' + displayName: 'Copy project files' + + # Publish pipeline artifact + - task: PublishPipelineArtifact@1 + inputs: + artifactName: 'nodejs-app' + targetPath: '$(Build.ArtifactStagingDirectory)' + displayName: 'Publish pipeline artifact' ``` -## 4 - Run your pipeline +In the updated pipeline, you'll: -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. "::: +- Install Node.js: The [UseNode@1 task](/azure/devops/pipelines/tasks/reference/use-node-v1) installs the specified Node.js version (18.x). +- Install dependencies: The npm install command installs the required dependencies for the Node.js project. +- Build the project: The npm run build command builds the Node.js project. +- Run Tests: The npm test command runs the project's test suite. +- Copy files: The [CopyFiles@2 task](/azure/devops/pipelines/tasks/reference/copy-files-v2) copies the necessary project files (for example, `src/**` and `public/**`) to the artifact staging directory. +- Publish pipeline artifact: The [PublishPipelineArtifact@1 task](/azure/devops/pipelines/tasks/reference/publish-pipeline-artifact-v1) publishes the files from the artifact staging directory as a pipeline artifact named nodejs-app. -::: moniker-end +## Run your pipeline -::: zone-end +Select **Validate and save**, then **Save**, **Run**, and **Run** again. +After your pipeline runs, verify that the job ran successfully and that you see a published artifact. +::: moniker range=">=azure-devops-2020" -::: zone pivot="pipelines-classic" +:::image type="content" source="media/node-artifact-run.png" alt-text="Screenshot of successful pipeline run with an artifact."::: -1. Fork the following repo at GitHub. +::: moniker-end - ``` - https://github.com/Azure-Samples/js-e2e-express-server - ``` +### [Classic](#tab/classic) -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. Select **GitHub** as the source for your code. +1. Under **Repository**, select your forked repository and **Continue**. +1. Select **Empty pipeline**, and select **Apply**. +1. Under **Agent specification** in the right pane, select **ubuntu-latest**. -3. Select **Process** under the **Tasks** tab in the pipeline editor and change the properties as follows: - * **Agent queue:** `Hosted Ubuntu Latest` +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. -4. Add the following tasks to the pipeline in the specified order: - * **npm** - * **Command:** `install` + 1. **npm** - * **npm** - * **Display name:** `npm test` - * **Command:** `custom` - * **Command and arguments:** `test` + 1. **npm** + - **Display name:** *npm test* + - **Command:** **custom** + - **Command and arguments:** *test* - * **Publish Test Results** - * Leave all the default values for properties + 1. **Publish Test Results** - * **Archive Files** - * **Root folder or file to archive:** `$(System.DefaultWorkingDirectory)` - * **Prepend root folder name to archive paths:** Unchecked + 1. **Archive files** + - **Root folder or file to archive:** *$(System.DefaultWorkingDirectory)* + - **Prepend root folder name to archive paths:** Uncheck - * **Publish Build Artifacts** - * Leave all the default values for properties + 1. **Publish build artifacts** -5. Save the pipeline and queue a build to see it in action. +1. Select **Save & queue**, and then select **Save and run**. + :::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. To extend your pipeline, you can: + +- Deploy to a cloud platform with a service like [Azure App Service](/azure/app-service/deploy-azure-pipelines) +- Publish as a [NPM package](../artifacts/npm.md) +- Deploy a static hosting service like [Azure Static Web Apps](/azure/devops/pipelines/tasks/reference/azure-static-web-app-v0) +- Containerize and deploy [Azure Kubernetes Service](/azure/aks/devops-pipeline) or other container orchestration platforms -## Next steps -Congratulations, you've successfully completed this quickstart! + +## Next steps > [!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..7b132c4221b 100644 --- a/docs/pipelines/ecosystems/kubernetes/deploy.md +++ b/docs/pipelines/ecosystems/kubernetes/deploy.md @@ -3,42 +3,42 @@ title: Deploy to Kubernetes 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' +ms.date: 05/27/2025 +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: +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: * [KubernetesManifest task](/azure/devops/pipelines/tasks/reference/kubernetes-manifest-v0): bake and deploy manifests to Kubernetes clusters with Helm, Kompose, or Kustomize * [Kubectl task](/azure/devops/pipelines/tasks/reference/kubernetes-v1): deploy, configure, and update a Kubernetes cluster in Azure Container Service by running kubectl commands -If you're using Azure Kubernetes Service with either task, 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. +If you use Azure Kubernetes Service with either task, the Azure Resource Manager service connection type is the best way to connect to a private cluster or a cluster with local accounts disabled. -For added deployment traceability, use a [Kubernetes resource](../../process/environments-kubernetes.md) in [environments](../../process/environments.md) with a Kubernetes task. +For added deployment traceability, use a [Kubernetes resource](../../process/environments-kubernetes.md) in [environments](../../process/environments.md) along with a Kubernetes task. -To get started with Azure Pipelines and Azure Kubernetes service, see [Build and deploy to Azure Kubernetes Service with Azure Pipelines](/azure/aks/devops-pipeline). To get started with Azure Pipelines, Kubernetes, and the canary deployment strategy specifically, see [Use a canary deployment strategy for Kubernetes deployments with Azure Pipelines](./canary-demo.md). +To get started with Azure Pipelines and Azure Kubernetes Service, see [Build and deploy to Azure Kubernetes Service with Azure Pipelines](/azure/aks/devops-pipeline). To get started with Azure Pipelines, Kubernetes, and the canary deployment strategy, see [Use a canary deployment strategy for Kubernetes deployments with Azure Pipelines](./canary-demo.md). ## KubernetesManifest task -The [KubernetesManifest task](/azure/devops/pipelines/tasks/reference/kubernetes-manifest-v0) checks for object stability before marking a task as success/failure. The task can also perform artifact substitution, add pipeline traceability-related annotations, simplify creation and referencing of imagePullSecrets, bake manifests, and aid in deployment strategy roll outs. +The [KubernetesManifest task](/azure/devops/pipelines/tasks/reference/kubernetes-manifest-v0) checks for object stability before marking a task as successful or failed. The task can also perform artifact substitution, add pipeline traceability-related annotations, simplify creation and referencing of imagePullSecrets, bake manifests, and aid in deployment strategy roll outs. > [!NOTE] -> While YAML-based pipeline support triggers on a single Git repository, if you need a trigger for a manifest file stored in another Git repository or if triggers are needed for Azure Container Registry or Docker Hub, you should use a classic pipeline instead of a YAML-based pipeline. +> YAML-based pipeline support triggers on a single Git repository. If you need a trigger for a manifest file stored in another Git repository, or if triggers are needed for Azure Container Registry or Docker Hub, use a classic pipeline instead of a YAML-based pipeline. -You can use the bake action in the [Kubernetes manifest task](/azure/devops/pipelines/tasks/reference/kubernetes-manifest-v0) to bake templates into Kubernetes manifest files. The action lets you use tools such as [Helm](https://helm.sh), [Kustomize](https://github.com/kubernetes-sigs/kustomize), and [Kompose](https://github.com/kubernetes/kompose). The bake action of the Kubernetes manifest task provides visibility into the transformation between input templates and the end manifest files that are used in deployments. You can consume baked manifest files downstream (in tasks) as inputs for the deploy action of the Kubernetes manifest task. +You can use the bake action in the [Kubernetes manifest task](/azure/devops/pipelines/tasks/reference/kubernetes-manifest-v0) to bake templates into Kubernetes manifest files. The action lets you use tools such as [Helm](https://helm.sh), [Kustomize](https://github.com/kubernetes-sigs/kustomize), and [Kompose](https://github.com/kubernetes/kompose). The bake action of the Kubernetes manifest task shows the transformation between input templates and the final manifest files used in deployments. You can consume baked manifest files downstream (in tasks) as inputs for the deploy action of the Kubernetes manifest task. -You can target [Kubernetes resources](../../process/environments-kubernetes.md) that are part of [environments](../../process/environments.md) with [deployment jobs](../../process/deployment-jobs.md). Using environments and resources deployment gives you access to better pipeline traceability so that you can diagnose deployment issues. You can also deploy to Kubernetes clusters with regular [jobs](../../process/phases.md) without the same health features. +Target [Kubernetes resources](../../process/environments-kubernetes.md) that are part of [environments](../../process/environments.md) with [deployment jobs](../../process/deployment-jobs.md). Using environments and resource deployments improves pipeline traceability, helping you diagnose deployment issues. You can also deploy to Kubernetes clusters with regular [jobs](../../process/phases.md) without the same health features. -The following YAML code is an example of baking manifest files from Helm charts +The following YAML code shows how to bake manifest files from Helm charts ```yaml steps: -- task: KubernetesManifest@0 +- task: KubernetesManifest@1 name: bake displayName: Bake K8s manifests from Helm chart inputs: @@ -46,34 +46,34 @@ steps: helmChart: charts/sample overrides: 'image.repository:nginx' -- task: KubernetesManifest@0 +- task: KubernetesManifest@1 displayName: Deploy K8s manifests inputs: kubernetesServiceConnection: someK8sSC namespace: default manifests: $(bake.manifestsBundle) containers: | - nginx: 1.7.9 + nginx: 1.24.0 ``` ## Kubectl task -As an alternative to the KubernetesManifest [KubernetesManifest task](/azure/devops/pipelines/tasks/reference/kubernetes-manifest-v0), you can use the [Kubectl task](/azure/devops/pipelines/tasks/reference/kubernetes-v1) to deploy, configure, and update a Kubernetes cluster in Azure Container Service by running kubectl commands. +As an alternative to the KubernetesManifest [KubernetesManifest task](/azure/devops/pipelines/tasks/reference/kubernetes-manifest-v0), use the [Kubectl task](/azure/devops/pipelines/tasks/reference/kubernetes-v1) to deploy, configure, and update a Kubernetes cluster in Azure Container Service by running kubectl commands. -The following example shows how a service connection is used to refer to the Kubernetes cluster. +This example shows how a service connection refers to the Kubernetes cluster. ```yaml - task: Kubernetes@1 displayName: kubectl apply inputs: connectionType: Kubernetes Service Connection - kubernetesServiceEndpoint: Contoso + kubernetesServiceConnection: Contoso #alias: kubernetesServiceEndpoint ``` ## Script task -You can also use `kubectl` with a [script task](../../scripts/cross-platform-scripting.md). +Use `kubectl` with a [script task](../../scripts/cross-platform-scripting.md). -The following example uses a script to run `kubectl`. +This example uses a script to run `kubectl`. ```yaml - script: | @@ -83,22 +83,22 @@ The following example uses a script to run `kubectl`. ## Kubernetes deployment strategies -The [Kubernetes manifest task](/azure/devops/pipelines/tasks/reference/kubernetes-manifest-v0) currently supports canary deployment strategy. Use canary deployment strategy to partially deploy new changes so that the new changes coexist with the current deployments before a full rollout. +The [Kubernetes manifest task](/azure/devops/pipelines/tasks/reference/kubernetes-manifest-v0) supports the canary deployment strategy. Use the canary deployment strategy to partially deploy new changes so the new changes coexist with current deployments before a full rollout. -For more information on canary deployments with pipelines, see [Use a canary deployment strategy for Kubernetes deployments with Azure Pipelines](./canary-demo.md). +For more information about canary deployments with pipelines, see [Use a canary deployment strategy for Kubernetes deployments with Azure Pipelines](./canary-demo.md). ## Multicloud Kubernetes deployments -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. +Kubernetes works the same way on all cloud providers. Use Azure Pipelines to deploy to Azure Kubernetes Service (AKS), Google Kubernetes Engine (GKE), Amazon Elastic Kubernetes Service (EKS), or clusters from 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 add 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) -> The generic provider approach based on existing service account works with clusters from any cloud provider, including Azure. The benefit of using the Azure Kubernetes Service option instead is that it creates new [ServiceAccount](https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/) and [RoleBinding](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#service-account-permissions) objects (instead of reusing an existing ServiceAccount) so that the newly created RoleBinding object can limit the operations of the ServiceAccount to the chosen namespace only. +> The generic provider approach, based on an existing service account, works with clusters from any cloud provider, including Azure. Using the Azure Kubernetes Service option creates new [ServiceAccount](https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/) and [RoleBinding](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#service-account-permissions) objects. This ensures the RoleBinding object limits the ServiceAccount's operations to the chosen namespace. -When you use the generic provider approach, [make sure 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. You need to grant permissions to the right services account so that the service account can be used by Azure Pipelines to create objects in the chosen namespace. +When using the generic provider approach, [ensure a RoleBinding exists](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#kubectl-create-rolebinding) that grants permissions in the `edit` `ClusterRole` to the desired service account. Grant permissions to the correct service account so Azure Pipelines can use it to create objects in the chosen namespace. ### Parallel deployments to multiple clouds @@ -119,7 +119,7 @@ jobs: deploy: steps: - checkout: self - - task: KubernetesManifest@0 + - task: KubernetesManifest@1 displayName: Deploy to Kubernetes cluster inputs: action: deploy @@ -136,7 +136,7 @@ jobs: deploy: steps: - checkout: self - - task: KubernetesManifest@0 + - task: KubernetesManifest@1 displayName: Deploy to Kubernetes cluster inputs: action: deploy @@ -153,7 +153,7 @@ jobs: deploy: steps: - checkout: self - - task: KubernetesManifest@0 + - task: KubernetesManifest@1 displayName: Deploy to Kubernetes cluster inputs: action: deploy @@ -170,7 +170,7 @@ jobs: deploy: steps: - checkout: self - - task: KubernetesManifest@0 + - task: KubernetesManifest@1 displayName: Deploy to Kubernetes cluster inputs: action: deploy @@ -187,7 +187,7 @@ jobs: deploy: steps: - checkout: self - - task: KubernetesManifest@0 + - task: KubernetesManifest@1 displayName: Deploy to Kubernetes cluster inputs: action: deploy 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/index/app-service-web.png b/docs/pipelines/ecosystems/media/index/app-service-web.png deleted file mode 100644 index 166a5e4d090..00000000000 Binary files a/docs/pipelines/ecosystems/media/index/app-service-web.png and /dev/null differ diff --git a/docs/pipelines/ecosystems/media/index/appservice.png b/docs/pipelines/ecosystems/media/index/appservice.png deleted file mode 100644 index bdf99076d05..00000000000 Binary files a/docs/pipelines/ecosystems/media/index/appservice.png and /dev/null differ diff --git a/docs/pipelines/ecosystems/media/index/azure-stack.png b/docs/pipelines/ecosystems/media/index/azure-stack.png deleted file mode 100644 index 15da8e24f8e..00000000000 Binary files a/docs/pipelines/ecosystems/media/index/azure-stack.png and /dev/null differ diff --git a/docs/pipelines/ecosystems/media/index/logo_Cplusplus.png b/docs/pipelines/ecosystems/media/index/logo_Cplusplus.png deleted file mode 100644 index dbd83845217..00000000000 Binary files a/docs/pipelines/ecosystems/media/index/logo_Cplusplus.png and /dev/null differ diff --git a/docs/pipelines/ecosystems/media/index/logo_anaconda.png b/docs/pipelines/ecosystems/media/index/logo_anaconda.png deleted file mode 100644 index c048ff507a0..00000000000 Binary files a/docs/pipelines/ecosystems/media/index/logo_anaconda.png and /dev/null differ diff --git a/docs/pipelines/ecosystems/media/index/logo_android.png b/docs/pipelines/ecosystems/media/index/logo_android.png deleted file mode 100644 index e701925931f..00000000000 Binary files a/docs/pipelines/ecosystems/media/index/logo_android.png and /dev/null differ diff --git a/docs/pipelines/ecosystems/media/index/logo_aspnetcore.png b/docs/pipelines/ecosystems/media/index/logo_aspnetcore.png deleted file mode 100644 index 0aebde8a38f..00000000000 Binary files a/docs/pipelines/ecosystems/media/index/logo_aspnetcore.png and /dev/null differ diff --git a/docs/pipelines/ecosystems/media/index/logo_dockercontainer.png b/docs/pipelines/ecosystems/media/index/logo_dockercontainer.png deleted file mode 100644 index ba99837a2eb..00000000000 Binary files a/docs/pipelines/ecosystems/media/index/logo_dockercontainer.png and /dev/null differ diff --git a/docs/pipelines/ecosystems/media/index/logo_go.png b/docs/pipelines/ecosystems/media/index/logo_go.png deleted file mode 100644 index 1ec3f54a3bd..00000000000 Binary files a/docs/pipelines/ecosystems/media/index/logo_go.png and /dev/null differ diff --git a/docs/pipelines/ecosystems/media/index/logo_java.png b/docs/pipelines/ecosystems/media/index/logo_java.png deleted file mode 100644 index 667d799141e..00000000000 Binary files a/docs/pipelines/ecosystems/media/index/logo_java.png and /dev/null differ diff --git a/docs/pipelines/ecosystems/media/index/logo_kubernetes.png b/docs/pipelines/ecosystems/media/index/logo_kubernetes.png deleted file mode 100644 index 1f299f7e796..00000000000 Binary files a/docs/pipelines/ecosystems/media/index/logo_kubernetes.png and /dev/null differ diff --git a/docs/pipelines/ecosystems/media/index/logo_linux-color.png b/docs/pipelines/ecosystems/media/index/logo_linux-color.png deleted file mode 100644 index ddbbc8c32b0..00000000000 Binary files a/docs/pipelines/ecosystems/media/index/logo_linux-color.png and /dev/null differ diff --git a/docs/pipelines/ecosystems/media/index/logo_net.png b/docs/pipelines/ecosystems/media/index/logo_net.png deleted file mode 100644 index 81fa9ba80b8..00000000000 Binary files a/docs/pipelines/ecosystems/media/index/logo_net.png and /dev/null differ diff --git a/docs/pipelines/ecosystems/media/index/logo_nodejs.png b/docs/pipelines/ecosystems/media/index/logo_nodejs.png deleted file mode 100644 index 6c6e9d69bc4..00000000000 Binary files a/docs/pipelines/ecosystems/media/index/logo_nodejs.png and /dev/null differ diff --git a/docs/pipelines/ecosystems/media/index/logo_npm.png b/docs/pipelines/ecosystems/media/index/logo_npm.png deleted file mode 100644 index 5bbf901eef1..00000000000 Binary files a/docs/pipelines/ecosystems/media/index/logo_npm.png and /dev/null differ diff --git a/docs/pipelines/ecosystems/media/index/logo_nuget.png b/docs/pipelines/ecosystems/media/index/logo_nuget.png deleted file mode 100644 index 145c0ed4670..00000000000 Binary files a/docs/pipelines/ecosystems/media/index/logo_nuget.png and /dev/null differ diff --git a/docs/pipelines/ecosystems/media/index/logo_php.png b/docs/pipelines/ecosystems/media/index/logo_php.png deleted file mode 100644 index faeaeb5dcdc..00000000000 Binary files a/docs/pipelines/ecosystems/media/index/logo_php.png and /dev/null differ diff --git a/docs/pipelines/ecosystems/media/index/logo_python.png b/docs/pipelines/ecosystems/media/index/logo_python.png deleted file mode 100644 index 19ba2900cd0..00000000000 Binary files a/docs/pipelines/ecosystems/media/index/logo_python.png and /dev/null differ diff --git a/docs/pipelines/ecosystems/media/index/logo_ruby.png b/docs/pipelines/ecosystems/media/index/logo_ruby.png deleted file mode 100644 index 9e46951e665..00000000000 Binary files a/docs/pipelines/ecosystems/media/index/logo_ruby.png and /dev/null differ diff --git a/docs/pipelines/ecosystems/media/index/logo_uwp.png b/docs/pipelines/ecosystems/media/index/logo_uwp.png deleted file mode 100644 index 1044ca26fba..00000000000 Binary files a/docs/pipelines/ecosystems/media/index/logo_uwp.png and /dev/null differ diff --git a/docs/pipelines/ecosystems/media/index/logo_visual-studio.png b/docs/pipelines/ecosystems/media/index/logo_visual-studio.png deleted file mode 100644 index ea25b7f1671..00000000000 Binary files a/docs/pipelines/ecosystems/media/index/logo_visual-studio.png and /dev/null differ diff --git a/docs/pipelines/ecosystems/media/index/logo_xamarin.png b/docs/pipelines/ecosystems/media/index/logo_xamarin.png deleted file mode 100644 index a27e27f8cda..00000000000 Binary files a/docs/pipelines/ecosystems/media/index/logo_xamarin.png and /dev/null differ diff --git a/docs/pipelines/ecosystems/media/index/logo_xcode.png b/docs/pipelines/ecosystems/media/index/logo_xcode.png deleted file mode 100644 index a9d2826f8cd..00000000000 Binary files a/docs/pipelines/ecosystems/media/index/logo_xcode.png and /dev/null differ diff --git a/docs/pipelines/ecosystems/media/index/sqldatabase.png b/docs/pipelines/ecosystems/media/index/sqldatabase.png deleted file mode 100644 index 3701094edc1..00000000000 Binary files a/docs/pipelines/ecosystems/media/index/sqldatabase.png and /dev/null differ diff --git a/docs/pipelines/ecosystems/media/index/virtualmachine.png b/docs/pipelines/ecosystems/media/index/virtualmachine.png deleted file mode 100644 index 25c2cc1bf36..00000000000 Binary files a/docs/pipelines/ecosystems/media/index/virtualmachine.png and /dev/null 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..03a5e410ad4 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-22.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-22.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..fa246d6349f 100644 --- a/docs/pipelines/ecosystems/python-webapp.md +++ b/docs/pipelines/ecosystems/python-webapp.md @@ -1,260 +1,579 @@ --- -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 + - sfi-image-nochange --- -# 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 +583,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 +986,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..e855906d4bc 100644 --- a/docs/pipelines/ecosystems/python.md +++ b/docs/pipelines/ecosystems/python.md @@ -1,151 +1,213 @@ --- -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' -ms.custom: devx-track-python, freshness-fy22q2 +monikerRange: "<=azure-devops" +ms.author: jukullam +ms.custom: + - devx-track-python + - freshness-fy22q2 + - sfi-image-nochange --- -# 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..0b9c51eddea 100644 --- a/docs/pipelines/ecosystems/ruby.md +++ b/docs/pipelines/ecosystems/ruby.md @@ -6,8 +6,8 @@ ms.assetid: 61052605-ec85-45ca-b57e-8664cd41c0ea ms.author: vijayma author: vijayma ms.reviewer: dastahel -ms.custom: seodec18, freshness-fy22q2, kr2b-contr-experiment -ms.date: 01/20/2022 +ms.custom: freshness-fy22q2, kr2b-contr-experiment +ms.date: 06/09/2025 monikerRange: azure-devops --- @@ -15,15 +15,15 @@ monikerRange: azure-devops [!INCLUDE [version-eq-azure-devops](../../includes/version-eq-azure-devops.md)] -This article explains how to automatically build Ruby projects. +Learn how to use Azure Pipelines to build, test, and deploy your Ruby application. ## Create the Azure Pipelines -Do the following steps to set up a pipeline for a Ruby app. +Follow these steps to set up a pipeline for a Ruby app. 1. Sign in to your Azure DevOps organization and go to your project. -1. Select **Pipelines** > **New pipeline**. +1. Go to **Pipelines** > **New pipeline**. 1. Select **GitHub** as the location of your source code. @@ -33,14 +33,14 @@ Do the following steps to set up a pipeline for a Ruby app. 1. Select the `Ruby` template for your pipeline. -1. A YAML file gets generated. Select **Save and run** > **Commit directly to the main branch**, and then choose **Save and run** again. +1. A YAML file is generated. Select **Save and run** > **Commit directly to the main branch**, and then select **Save and run** again. 1. Wait for the run to finish. You have a working YAML file (`azure-pipelines.yml`) in your repository that's ready for you to customize. > [!TIP] -> To make changes to the YAML file as described in this article, select the pipeline in the **Pipelines** page, and then **Edit** the `azure-pipelines.yml` file. +> To make changes to the YAML file described in this article, select the pipeline on the **Pipelines** page, and then select **Edit** for the `azure-pipelines.yml` file. ## Build environment @@ -50,18 +50,18 @@ For the exact versions of Ruby that are preinstalled, refer to [Microsoft-hosted ### Use a specific Ruby version -Add the [Use Ruby Version](/azure/devops/pipelines/tasks/reference/use-ruby-version-v0) task to set the version of Ruby used in your pipeline. This snippet adds Ruby 2.4 or later to the path and sets subsequent pipeline tasks to use it. +Add the [Use Ruby Version](/azure/devops/pipelines/tasks/reference/use-ruby-version-v0) task to set the Ruby version in your pipeline. This snippet adds Ruby 3.4 or later to the path and sets subsequent pipeline tasks to use it. ```yaml -# https://learn.microsoft.com/azure/devops/pipelines/ecosystems/ruby pool: - vmImage: 'ubuntu-latest' # other options: 'macOS-latest', 'windows-latest' + vmImage: 'ubuntu-latest' steps: -- task: UseRubyVersion@0 +- task: UseRubyVersion@0 inputs: - versionSpec: '>= 2.5' + versionSpec: '>= 3.4' addToPath: true + displayName: 'Set Ruby version' ``` ### Install Rails @@ -70,18 +70,18 @@ To install Rails, add the following snippet to your `azure-pipelines.yml` file. ```yaml - script: gem install rails && rails -v - displayName: 'gem install rails' + displayName: 'Install Rails' ``` ### Install dependencies -To use Bundler to install dependencies, add the following snippet to your `azure-pipelines.yml` file. +Use Bundler to install dependencies by adding the following snippet to your `azure-pipelines.yml` file. ```yaml - script: | - CALL gem install bundler + gem install bundler bundle install --retry=3 --jobs=4 - displayName: 'bundle install' + displayName: 'Install dependencies with Bundler' ``` ### Run Rake @@ -95,9 +95,9 @@ To execute Rake in the context of the current bundle (as defined in your Gemfile ### Publish test results -The sample code includes unit tests written using [RSpec](https://rspec.info/). When Rake is run by the previous step, it runs the RSpec tests. The RSpec RakeTask in the Rakefile has been configured to produce JUnit style results using the RspecJUnitFormatter. +The sample code includes unit tests written with [RSpec](https://rspec.info/). When Rake runs in the previous step, it executes the RSpec tests. The RSpec RakeTask in the Rakefile is configured to produce JUnit-style results using the RspecJUnitFormatter. -Add the [Publish Test Results](/azure/devops/pipelines/tasks/reference/publish-test-results-v2) task to publish JUnit style test results to the server. You get a rich test reporting experience that you can use for troubleshooting any failed tests and for test timing analysis. +Add the [Publish Test Results](/azure/devops/pipelines/tasks/reference/publish-test-results-v2) task to publish JUnit-style test results to the server. ```yaml - task: PublishTestResults@2 @@ -110,16 +110,17 @@ Add the [Publish Test Results](/azure/devops/pipelines/tasks/reference/publish-t The sample code uses [SimpleCov](https://github.com/colszowka/simplecov) to collect code coverage data when unit tests get run. SimpleCov is configured to use Cobertura and HTML report formatters. -Add the [Publish Code Coverage Results](/azure/devops/pipelines/tasks/reference/publish-code-coverage-results-v1) task to publish code coverage results to the server. When you do so, coverage metrics can be seen in the build summary and HTML reports can be downloaded for further analysis. +Add the [Publish Code Coverage Results](/azure/devops/pipelines/tasks/reference/publish-code-coverage-results-v2) task to publish code coverage results to the server. This lets you view 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' reportDirectory: '$(System.DefaultWorkingDirectory)/**/coverage' + failIfCoverageEmpty: true ``` ## Build an image and push to container registry -For your Ruby app, you can also [build an image](containers/build-image.md) and [push it to a container registry](containers/push-image.md). +For your Ruby app, you can [build an image](containers/build-image.md) and [push it to a container registry](containers/push-image.md). 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..e4cd7abec64 100644 --- a/docs/pipelines/get-started/clone-import-pipeline.md +++ b/docs/pipelines/get-started/clone-import-pipeline.md @@ -2,8 +2,9 @@ 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' +ms.custom: sfi-image-nochange --- # Clone or import a pipeline @@ -12,6 +13,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 +25,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 +80,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 +108,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 +169,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..32da2871c7d 100644 --- a/docs/pipelines/integrations/configure-pipelines-work-tracking.md +++ b/docs/pipelines/integrations/configure-pipelines-work-tracking.md @@ -6,25 +6,26 @@ ms.subservice: azure-devops-pipelines-integrations ms.topic: how-to ms.author: chcomley author: chcomley -ms.custom: cross-service monikerRange: '<= azure-devops' -ms.date: 04/01/2022 +ms.date: 09/09/2024 +ms.custom: + - cross-service + - sfi-image-nochange --- # 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 +44,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 +56,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 +68,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 +81,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 +97,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 +106,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 +119,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 +128,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 +150,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 +239,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 +257,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 +279,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 +300,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 +311,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 +322,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 +334,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 +350,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 +378,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. + +### Cargo service connection -### Basic authentication +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 +263,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 +277,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 +374,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 +406,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 +438,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 +520,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 +537,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 npm registry. | | 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 +721,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..518f3fbbcb0 100644 --- a/docs/pipelines/library/variable-groups.md +++ b/docs/pipelines/library/variable-groups.md @@ -1,571 +1,509 @@ --- -title: Variable groups for Azure Pipelines -ms.custom: seodec18, devx-track-azurecli, pipelinesresourcesrefresh +title: Manage variable groups 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' +ms.custom: + - devx-track-azurecli + - pipelinesresourcesrefresh + - sfi-image-nochange --- -# 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-classic-pipelines.md b/docs/pipelines/migrate/from-classic-pipelines.md deleted file mode 100644 index 87b5b29c9c0..00000000000 --- a/docs/pipelines/migrate/from-classic-pipelines.md +++ /dev/null @@ -1,108 +0,0 @@ ---- -title: Migrate from Classic to YAML pipelines -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 -monikerRange: azure-devops ---- - -# Migrate your Classic pipeline to YAML - -[!INCLUDE [version-eq-azure-devops](../../includes/version-eq-azure-devops.md)] - -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. - -## Prerequisites - -Make sure you have the following items before you begin. - -- 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 working pipeline that uses the Classic user interface (UI) editor. -- A sample YAML pipeline file in your code. Create a sample YAML pipeline in the following section. - -## Create a sample YAML pipeline - -Do the following steps to create a sample YAML pipeline, which you'll update later with your exported code from the Classic UI editor. - -1. Sign in to your organization (```https://dev.azure.com/{yourorganization}```) and select your project. - -2. Select **Pipelines**, and then **New pipeline**. - - :::image type="content" source="media/pipelines-new-pipeline.png" alt-text="Two buttons to select for new pipeline creation."::: - -3. Select the location for your source code as either **GitHub** or **Azure Repos Git**. - - :::image type="content" source="media/source-code-location.png" alt-text="List of possible selections for your source code."::: - -4. Select a repository. - - :::image type="content" source="media/select-repository.png" alt-text="Page where you select a repository for your source code pipeline."::: - -5. On the Configure your pipeline page, select **Starter pipeline**. - - :::image type="content" source="media/select-pipeline-template.png" alt-text="List of templates to choose from for configuring your new pipeline."::: - -6. Select **Save and run**. - - :::image type="content" source="media/save-run-new-yaml-pipeline.png" alt-text="Review page where you select Save and run."::: - -7. Enter your commit message, select **Commit directly to the main branch**, and then choose **Save and run** again. A new run starts and it's committed to the repository. Wait for the run to finish. - - :::image type="content" source="media/commit-save-run.png" alt-text="Commit message to commit to the main branch, and then select Save and run button."::: - -## 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. - -2. Select the ellipses (...), and then select **Export to YAML**. - - :::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. - -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). - -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). - -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. - - :::image type="content" source="media/task-assistant-yaml.png" alt-text="Configure your pipeline task with Task Assistant."::: - -7. **Save and run** your pipeline. - -## Clean up resources - -If you're not going to use this sample pipeline anymore, delete it from your project. Deletion is permanent and includes all builds and associated artifacts. - -1. Select the ellipses (...) and select **Delete**. - -2. Enter the name of your pipeline to permanently delete it, and then select **Delete**. - -## FAQ - -### Is there a task in YAML pipelines to create work items when there's a build failure? - -YAML pipelines don't have a [Create work item on failure setting](../build/options.md#create-a-work-item-on-failure) like classic build pipelines. You have a couple of options for creating this functionality yourself. -- You can use a script or PowerShell task and call the [REST API](/rest/api/azure/devops/pipelines/). -- You can use Azure CLI to call [az boards work-item create](/cli/azure/boards/work-item#az-boards-work-item-create) in your pipeline. [See an example](../customize-pipeline.md#create-work-item-on-failure) of using the CLI to create a bug on failure. - -## Next steps - -Learn about the feature differences between YAML and Classic pipelines. - -> [!div class="nextstepaction"] -> [Use Azure Pipelines](../get-started/pipelines-get-started.md#feature-availability) - -## Related articles - -- [Customize your pipeline](../customize-pipeline.md) -- [YAML pipeline editor basics](../get-started/yaml-pipeline-editor.md) -- [Library of assets](../library/index.md) -- [Define approvals and checks](../release/approvals/approvals.md) 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..ad1979fe6c4 100644 --- a/docs/pipelines/packages/nuget-restore.md +++ b/docs/pipelines/packages/nuget-restore.md @@ -1,94 +1,76 @@ --- -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-a-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 later, 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 ## If you're using Ubuntu 24.04 or later, use the following command instead: dotnet 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 `. If you're using Ubuntu 24.04 or later, use the following command instead: `dotnet 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 +78,70 @@ 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 ## If you're using Ubuntu 24.04 or later, use the following command instead: dotnet 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 `. If you're using Ubuntu 24.04 or later, use the following command instead: `dotnet 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" +ms.custom: sfi-image-nochange --- # Define approvals and checks @@ -16,12 +16,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 +46,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 +103,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 +124,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 +156,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 +173,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 +257,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 +295,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 +304,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 +322,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 +348,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 +379,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..a4f01d0230c 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: 05/14/2025 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). +Use an Azure DevOps multistage pipeline to divide your CI/CD process into stages that represent different parts of your development cycle. A multistage pipeline gives 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. @@ -25,41 +26,40 @@ The example code in this exercise is for a .NET web application for a pretend sp ## Prerequisites -* 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 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. +| **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.| +## Fork the project -## 1 - Fork the project - -Fork the following sample repository at GitHub. +Fork the following sample repository on 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,23 +69,23 @@ 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 \ --name tailspin-space-game-web-dev-$webappsuffix \ --resource-group tailspin-space-game-rg \ --plan tailspin-space-game-asp \ - --runtime "DOTNET|6.0" + --runtime "DOTNET|8.0" az webapp create \ --name tailspin-space-game-web-staging-$webappsuffix \ --resource-group tailspin-space-game-rg \ --plan tailspin-space-game-asp \ - --runtime "DOTNET|6.0" + --runtime "DOTNET|8.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 +96,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 +107,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 +115,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-22.04' + demands: + - npm + + variables: + wwwrootDir: 'Tailspin.SpaceGame.Web/wwwroot' + dotnetSdkVersion: '8.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 +196,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 +207,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 +223,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-22.04' + demands: + - npm + + variables: + wwwrootDir: 'Tailspin.SpaceGame.Web/wwwroot' + dotnetSdkVersion: '8.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-22.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 +334,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 +359,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-22.04' + demands: + - npm + + variables: + wwwrootDir: 'Tailspin.SpaceGame.Web/wwwroot' + dotnetSdkVersion: '8.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-22.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-22.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 +505,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..339e83da23e 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: @@ -274,7 +240,7 @@ jobs: deploy: steps: # No need to explicitly pass the connection details. - - task: KubernetesManifest@0 + - task: KubernetesManifest@1 displayName: Deploy to Kubernetes cluster inputs: action: deploy @@ -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: @@ -353,7 +323,7 @@ jobs: deploy: steps: - script: echo deploy updates... -        - task: KubernetesManifest@0 +        - task: KubernetesManifest@1           inputs:             action: $(strategy.action)                   namespace: 'default' @@ -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..006986b85f3 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,19 +173,21 @@ stages: displayName: Production pool: vmImage: $(vmImageName) - environment: $(envName).$(resourceName) + environment: + name: $(envName).$(resourceName) + resourceType: Kubernetes strategy: runOnce: deploy: steps: - - task: KubernetesManifest@0 + - task: KubernetesManifest@1 displayName: Create imagePullSecret inputs: action: createSecret secretName: $(imagePullSecret) dockerRegistryEndpoint: $(dockerRegistryServiceConnection) - - task: KubernetesManifest@0 + - task: KubernetesManifest@1 displayName: Deploy to Kubernetes cluster inputs: action: deploy @@ -198,7 +205,9 @@ stages: pool: vmImage: $(vmImageName) - environment: $(envName).$(resourceName) + environment: + name: $(envName).$(resourceName) + resourceType: Kubernetes strategy: runOnce: deploy: @@ -212,7 +221,7 @@ stages: useConfigurationFile: true inline: '{ "kind": "Namespace", "apiVersion": "v1", "metadata": { "name": "$(k8sNamespaceForPR)" }}' - - task: KubernetesManifest@0 + - task: KubernetesManifest@1 displayName: Create imagePullSecret inputs: action: createSecret @@ -220,7 +229,7 @@ stages: namespace: $(k8sNamespaceForPR) dockerRegistryEndpoint: $(dockerRegistryServiceConnection) - - task: KubernetesManifest@0 + - task: KubernetesManifest@1 displayName: Deploy to the new namespace in the Kubernetes cluster inputs: action: 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..2457381f6aa 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,20 +89,20 @@ 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: steps: - - task: KubernetesManifest@0 + - task: KubernetesManifest@1 displayName: Deploy to Kubernetes cluster inputs: action: 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..02ab30d9f9e 100644 --- a/docs/pipelines/process/includes/parameter-data-types.md +++ b/docs/pipelines/process/includes/parameter-data-types.md @@ -4,12 +4,14 @@ 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 | |-----------|-------| | `string` | string +| `stringList` | a list of items, multiple can be selected. Not available in templates | `number` | may be restricted to `values:`, otherwise any number-like string is accepted | `boolean` | `true` or `false` | `object` | any YAML structure @@ -22,60 +24,86 @@ ms.date: 02/22/2023 | `stage` | a single stage | `stageList` | sequence of stages -The step, stepList, job, jobList, deployment, deploymentList, stage, and stageList data types all use standard YAML schema format. This example includes string, number, boolean, object, step, and stepList. +The `step`, `stepList`, `job`, `jobList`, `deployment`, `deploymentList`, `stage`, `stringList`, and `stageList` data types all use standard YAML schema format. This example includes `string`, `number`, `boolean`, `object`, `step`, and `stepList`. + +> [!NOTE] +> The `stringList` data type isn't available in templates. Use the `object` data type in templates instead. ```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' + +- name: myMultiString # Define a parameter named 'myMultiString' + type: string # The parameter type is string + default: default # Default value is 'default', only one default + values: # Allowed values for 'myMultiString' + - default + - ubuntu + +- name: myStringlist # Define a parameter named 'myStringlist' + type: stringList # The parameter type is stringList + displayName: Regions + values: # Allowed values for 'myStringlist' + - WUS + - CUS + - EUS + default: # Default values + - WUS + - CUS + +- 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 -trigger: none +- 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 }} # Use the step from the 'myStep' parameter + +- job: stringList # Define a job named 'stringList' steps: - - ${{ parameters.myStep }} + - ${{ each region in parameters.myStringlist }}: + - script: echo ${{region}} ``` \ 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..d4d78c18502 100644 --- a/docs/pipelines/process/includes/variable-groups-link-secrets.md +++ b/docs/pipelines/process/includes/variable-groups-link-secrets.md @@ -4,38 +4,62 @@ 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 + - sfi-image-nochange --- -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..8ba5eeba53a 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 - -::: 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 +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. -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,52 +699,46 @@ 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. +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 +# test and upload my code as an artifact named Website jobs: - job: Build pool: vmImage: 'ubuntu-latest' steps: - script: npm test - - task: PublishBuildArtifacts@1 + - task: PublishPipelineArtifact@1 inputs: - pathtoPublish: '$(System.DefaultWorkingDirectory)' - artifactName: WebSite + artifactName: Website + targetPath: '$(System.DefaultWorkingDirectory)' # download the artifact and deploy it only if the build job succeeded - job: Deploy @@ -906,43 +746,30 @@ jobs: vmImage: 'ubuntu-latest' steps: - checkout: none #skip checking out the default repository resource - - task: DownloadBuildArtifacts@0 - displayName: 'Download Build Artifacts' + - task: DownloadPipelineArtifact@2 + displayName: 'Download Pipeline Artifact' inputs: - artifactName: WebSite - downloadPath: $(System.DefaultWorkingDirectory) - + artifactName: Website + targetPath: '$(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 +788,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..9e1bf90e4df 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,12 @@ 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`). + +## Related content + +- [Scheduled triggers](scheduled-triggers.md) +- [Classic pipeline triggers](../release/pipeline-triggers-classic.md) +- [Classic release triggers](../release/triggers.md) \ No newline at end of file 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..02b372374c6 100644 --- a/docs/pipelines/process/run-number.md +++ b/docs/pipelines/process/run-number.md @@ -1,129 +1,114 @@ --- -title: Run (build) number -ms.custom: seodec18 -description: Customize pipeline run number in Azure Pipelines or Azure DevOps Server. +title: Configure 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)] +Azure Pipelines assigns a unique run number (also called a build number) to each pipeline execution. You can customize these numbers to make them more meaningful for your team, using variables, tokens, and naming patterns. -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`. - - - -#### [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. +You can only customize the run number at the root level of your pipeline using the `name` property. Set the `name` property at the [pipeline](/azure/devops/pipelines/yaml-schema/pipeline) level. The `name` property isn't supported in templates or stages. + +The following code sets a custom run number format like `project_def_main_202408281`: ```yaml -name: $(TeamProject)_$(Build.DefinitionName)_$(SourceBranchName)_$(Date:yyyyMMdd)$(Rev:r) +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, 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 +116,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..5775c187a31 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.custom: devx-track-azurecli, ai-assisted ms.assetid: 0d207cb2-fcef-49f8-b2bf-ddb4fcf5c47a -ms.date: 01/04/2023 -monikerRange: '>= azure-devops-2019' +ms.date: 06/09/2025 +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 that shows 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 can succeed, fail, be canceled, or not complete. Understanding these outcomes helps 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 can't use [variables](variables.md) to resolve service connection or environment names, because the pipeline authorizes resources before a stage starts 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. +Azure Pipelines requests an [agent](../agents/agents.md) from the [pool](../agents/pools-queues.md) to run a job. The process differs 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) +The Microsoft-hosted pool is conceptually one global pool of machines, but it's physically divided into multiple pools 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. Before a step starts, all previous steps must finish or be 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 automatically convert 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,98 +118,53 @@ 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 or fail with issues, 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 doesn't save the job from failing. Jobs can't return to success after failing. -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. +This command lists the first three pipeline runs with a status of **completed** and a result of **succeeded**, and shows the result in table format. ```azurecli az pipelines runs list --status completed --result succeeded --top 3 --output table @@ -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. +This command shows details for the pipeline run with ID **123**, displays 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 using the [az pipelines runs tag delete](/cli/azure/pipelines/runs/tag#az-pipelines-runs-tag-delete) command. This 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..11c620d3f0c 100644 --- a/docs/pipelines/process/scheduled-triggers.md +++ b/docs/pipelines/process/scheduled-triggers.md @@ -2,10 +2,12 @@ title: Configure schedules to run pipelines description: Configure schedules to run pipelines ms.topic: conceptual +ms.collection: 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 +ms.update-cycle: 180-days monikerRange: '<= azure-devops' --- @@ -13,10 +15,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 +26,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 +38,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 +222,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 +255,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 +273,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 +291,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 +336,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 +382,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 +408,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 +426,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 +439,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 +452,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 +471,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 +509,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 +574,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..b89bd314b0a 100644 --- a/docs/pipelines/process/stages.md +++ b/docs/pipelines/process/stages.md @@ -1,24 +1,19 @@ --- 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: 03/28/2025 monikerRange: '<= azure-devops' --- -# Add stages, dependencies, & conditions +# Add stages, dependencies, and conditions [!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 group actions in your software development process, like building the app, running tests, and deploying 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" -::: 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. -> [!NOTE] -> Support for stages was added in Azure DevOps Server 2019.1. - -::: moniker-end - -::: moniker range="< azure-devops-2019" - -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. A stage can have up to 256 jobs. ::: 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. Examples include running functional tests, deploying to preproduction, and deploying to production. 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,64 +48,73 @@ 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" -::: moniker range=">=azure-devops-2019" - -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. +In the simplest case, you don't need logical boundaries in your pipeline. For those scenarios, you can directly specify the jobs in your YAML file without the `stages` keyword. For example, if you have a simple pipeline that builds and tests a small application without requiring separate environments or deployment steps, you can define all the jobs directly without using stages. ```yaml -# this has one implicit stage and one implicit job pool: vmImage: 'ubuntu-latest' -steps: -- bash: echo "Hello world" + +jobs: +- job: BuildAndTest + steps: + - script: echo "Building the application" + - script: echo "Running tests" ``` +This pipeline has one implicit stage and two jobs. The `stages` keyword isn't used because there's only one stage. + ```yaml -# this pipeline has one implicit stage jobs: -- job: A +- job: Build steps: - - bash: echo "A" + - bash: echo "Building" -- job: B +- job: Test steps: - - bash: echo "B" + - bash: echo "Testing" ``` -If you organize your pipeline into multiple stages, you use the `stages` keyword. +To organize your pipeline into multiple stages, use the `stages` keyword. This YAML defines a pipeline with two stages where each stage contains multiple jobs, and each job has specific steps to execute. ```yaml stages: - stage: A + displayName: "Stage A - Build and Test" jobs: - job: A1 + displayName: "Job A1 - build" + steps: + - script: echo "Building the application in Job A1" + displayName: "Build step" - job: A2 + displayName: "Job A2 - Test" + steps: + - script: echo "Running tests in Job A2" + displayName: "Test step" - stage: B + displayName: "Stage B - Deploy" jobs: - job: B1 + displayName: "Job B1 - Deploy to Staging" + steps: + - script: echo "Deploying to staging in Job B1" + displayName: "Staging deployment step" - job: B2 + displayName: "Job B2 - Deploy to Production" + steps: + - script: echo "Deploying to production in Job B2" + displayName: "Production deployment step" ``` -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" +::: moniker range="<=azure-devops" -> [!NOTE] -> In Azure DevOps Server 2019, pools can only be specified at job level. - -::: moniker-end +If you specify a `pool` at the stage level, all jobs in that stage use that pool unless the stage is specified at the job level. -::: moniker range=">=azure-devops-2019" ```yaml stages: @@ -136,30 +126,12 @@ stages: pool: JobPool ``` -The full syntax to specify a stage is: - -```yaml -stages: -- stage: string # name of the stage, A-Z, a-z, 0-9, and underscore - displayName: string # friendly name to display in the UI - dependsOn: string | [ string ] - condition: string - pool: string | pool - variables: { string: string } | [ variable | variableReference ] - jobs: [ job | templateReference] -``` - -::: 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. +To add a stage to your release pipeline, select the release pipeline on the **Releases** page, select **Edit**, and then select the **Pipeline** tab. While the most important part of defining a stage is the automation tasks, you can also configure several properties and options for a stage in a release pipeline. You can: @@ -168,7 +140,7 @@ for a stage in a release pipeline. You can: * Designate one user or a group to be the stage owner. Stage owners get notified whenever a deployment to that - stage fails. Being a stage owner doesn't automatically come with any permissions. + stage fails. Stage ownership doesn't automatically include permissions. * Delete the stage from the pipeline. * Change the order of stages. * Save a copy of the stage as a [stage template](../release/env-templates.md). @@ -182,43 +154,34 @@ 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" -::: moniker range=">=azure-devops-2019" - -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. +When you define multiple stages in a pipeline, they run sequentially by default in the order 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. +For more information on how to define stages, see [stages in the YAML schema](/azure/devops/pipelines/yaml-schema/stages). -The syntax for defining multiple stages and their dependencies is: - -```yaml -stages: -- stage: string - dependsOn: string - condition: string -``` +The following example stages run sequentially. If you don't use a `dependsOn` keyword, stages run in the order they're defined. -Example stages that run sequentially: ```yaml -# if you do not use a dependsOn keyword, stages run in the order they are defined stages: -- stage: QA +- stage: Build + displayName: "Build Stage" jobs: - - job: - ... + - job: BuildJob + steps: + - script: echo "Building the application" + displayName: "Build Step" -- stage: Prod +- stage: Test + displayName: "Test Stage" jobs: - - job: - ... + - job: TestJob + steps: + - script: echo "Running tests" + displayName: "Test Step" ``` Example stages that run in parallel: @@ -226,52 +189,53 @@ Example stages that run in parallel: ```yaml stages: - stage: FunctionalTest + displayName: "Functional Test Stage" jobs: - - job: - ... + - job: FunctionalTestJob + steps: + - script: echo "Running functional tests" + displayName: "Run Functional Tests" - stage: AcceptanceTest - dependsOn: [] # this removes the implicit dependency on previous stage and causes this to run in parallel + displayName: "Acceptance Test Stage" + dependsOn: [] # Runs in parallel with FunctionalTest jobs: - - job: - ... + - job: AcceptanceTestJob + steps: + - script: echo "Running acceptance tests" + displayName: "Run Acceptance Tests" ``` -Example of fan-out and fan-in: +Example of fan-out and fan-in behavior: ```yaml stages: - stage: Test - stage: DeployUS1 - dependsOn: Test # this stage runs after Test + dependsOn: Test # stage runs after Test - stage: DeployUS2 - dependsOn: Test # this stage runs in parallel with DeployUS1, after Test + dependsOn: Test # stage runs in parallel with DeployUS1, after Test - stage: DeployEurope - dependsOn: # this stage runs after DeployUS1 and DeployUS2 + dependsOn: # stage runs after DeployUS1 and DeployUS2 - DeployUS1 - DeployUS2 ``` ::: 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: +Control dependencies by setting 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 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. +* Stages run with a trigger or are manually started. +* With an **After release** trigger, a stage starts as soon as the release begins, running in parallel with other stages that have the same trigger. +* With an **After stage** trigger, a stage starts after all 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 +245,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 +279,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,19 +290,13 @@ When you specify **After release** or **After stage** triggers, you can also spe ## Specify queuing policies #### [YAML](#tab/yaml/) -::: moniker range=">= azure-devops-2019" -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 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 might 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 #### [Classic](#tab/classic/) -In some cases, you may be able to generate builds faster than -they can be deployed. Alternatively, you may configure multiple +In some cases, you might be able to generate builds faster than +they can be deployed. Alternatively, you might configure multiple [agents](../agents/agents.md) and, for example, be creating releases from the same release pipeline for deployment of different artifacts. In such cases, it's useful to be able to control how multiple releases are queued into a @@ -365,57 +307,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 +357,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 might have a YAML template that injects a stage that performs malware detection in all pipelines. If you set `isSkippable: false` for this stage, your pipeline won't be able to skip malware detection. + +In the following example, the Malware detection stage is marked as nonskippable, 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 nonskippable, it shows 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..97ec0ef8a59 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' --- @@ -25,7 +24,7 @@ in an expression. Only predefined variables can be used in template expressions. For example, you define a template: ```yaml -# File: steps/msbuild.yml +# File: steps/vsbuild.yml parameters: - name: 'solution' @@ -33,12 +32,14 @@ parameters: type: string steps: -- task: msbuild@1 +- task: VSBuild@1 inputs: solution: ${{ parameters['solution'] }} # index syntax -- task: vstest@2 +- task: VSTest@3 inputs: - solution: ${{ parameters.solution }} # property dereference syntax + testSelector: 'testAssemblies' + testAssemblyVer2: ${{ parameters.solution }} # property dereference syntax + searchFolder: '$(System.DefaultWorkingDirectory)' ``` Then you reference the template and pass it the optional `solution` parameter: @@ -47,7 +48,7 @@ Then you reference the template and pass it the optional `solution` parameter: # File: azure-pipelines.yml steps: -- template: steps/msbuild.yml +- template: steps/vsbuild.yml parameters: solution: my.sln ``` @@ -114,9 +115,9 @@ jobs: steps: - script: cred-scan - ${{ parameters.preBuild }} - - task: msbuild@1 + - task: VSBuild@1 - ${{ parameters.preTest }} - - task: vstest@2 + - task: VSTest@3 - ${{ parameters.preSign }} - script: sign ``` @@ -151,8 +152,8 @@ jobs: arch: x86 ${{ insert }}: ${{ parameters.additionalVariables }} steps: - - task: msbuild@1 - - task: vstest@2 + - task: VSBuild@1 + - task: VSTest@3 ``` ```yaml @@ -174,24 +175,24 @@ For example, to insert into a sequence in a template: parameters: - name: 'toolset' - default: msbuild + default: vsbuild type: string values: - - msbuild + - vsbuild - dotnet steps: # msbuild - ${{ if eq(parameters.toolset, 'msbuild') }}: - - task: msbuild@1 - - task: vstest@2 + - task: VSBuild@1 + - task: VSTest@3 # dotnet - ${{ if eq(parameters.toolset, 'dotnet') }}: - - task: dotnet@1 + - task: UseDotNet@2 inputs: command: build - - task: dotnet@1 + - task: UseDotNet@2 inputs: command: test ``` @@ -246,6 +247,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). @@ -285,6 +317,36 @@ jobs: - script: echo So will this! ``` +You can also use `stringList` to define and interate over parameters that contain a list of items. + +> [!NOTE] +> The `stringList` data type isn't available in templates. Use the `object` data type in templates instead. + + +```yaml +parameters: +- name: regions + type: stringList + displayName: Regions + values: + - WUS + - CUS + - EUS + default: + - WUS + - EUS + +stages: +- ${{ each stage in parameters.regions}}: + - stage: ${{stage}} + displayName: Deploy to ${{stage}} + jobs: + - job: + steps: + - script: ./deploy ${{stage}} +``` + + You can also manipulate the properties of whatever you're iterating over. For example, to add more dependencies: @@ -327,12 +389,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..10d008003a2 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 @@ -185,12 +208,14 @@ steps: env: SOLUTION: ${{ parameters.solution }} displayName: Check for required parameters -- task: msbuild@1 +- task: VSBuild@1 inputs: solution: ${{ parameters.solution }} -- task: vstest@2 +- task: VSTest@3 inputs: - solution: ${{ parameters.solution }} + testSelector: 'testAssemblies' + testAssemblyVer2: ${{ parameters.solution }} + searchFolder: '$(System.DefaultWorkingDirectory)' ``` To show that the template fails if it's missing the required parameter: @@ -207,111 +232,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..bc2fb7cbfbc 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,11 +456,12 @@ 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). -Use [parameters](template-parameters.md#passing-parameters) instead of variables when you want to restrict type. + +> [!NOTE] +> Use [parameters](template-parameters.md#passing-parameters) instead of variables for added security such as specifying type. For more information on the importance of using parameters for shell tasks, refer to the [Enable shell tasks arguments parameter validation documentation](../security/inputs.md#enable-shell-tasks-arguments-parameter-validation). In this example, the variable `favoriteVeggie` is included in `azure-pipelines.yml`. @@ -427,7 +480,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 +528,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 +646,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 +665,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 +710,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 +725,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 +735,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 may also use `@self` to refer to the repository where the original pipeline was found. +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 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 +789,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 +817,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..dcecd288742 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: @@ -480,21 +493,21 @@ pool: vmImage: 'ubuntu-latest' steps: -- task: AzureFileCopy@4 +- task: AzureFileCopy@6 inputs: - SourcePath: 'my/path' - azureSubscription: 'my-subscription' - Destination: 'AzureVMs' - storage: 'my-storage' - resourceGroup: 'my-rg' - vmsAdminUserName: $(VMS_USER) - vmsAdminPassword: $(VMS_PASS) + SourcePath: 'my/path' # Specify the source path + azureSubscription: 'my-subscription' # Azure subscription name + Destination: 'AzureVMs' # Destination type + storage: 'my-storage' # Azure storage account name + resourceGroup: 'my-resource-group' # Resource group name + vmsAdminUserName: $(VMS_USER) # Admin username for the VM + vmsAdminPassword: $(VMS_PASS) # Admin password for the VM + CleanTargetBeforeCopy: false # Do not clean the target before copying ``` - ### 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 +545,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 +552,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 +574,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..798d5858980 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 Monitor 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..bec09fa31c8 100644 --- a/docs/pipelines/release/approvals/servicenow.md +++ b/docs/pipelines/release/approvals/servicenow.md @@ -1,191 +1,235 @@ --- -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' +ms.custom: sfi-image-nochange "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/automate-service-connections.md b/docs/pipelines/release/automate-service-connections.md new file mode 100644 index 00000000000..18c16931609 --- /dev/null +++ b/docs/pipelines/release/automate-service-connections.md @@ -0,0 +1,225 @@ +--- +title: Use scripts to automate Azure Resource Manager with workload identity service connections +description: Learn how to automate Azure Resource Manager service connections in Azure Pipelines with workload identity. Save time, ensure consistency, and reduce errors. +ms.topic: how-to +ms.author: jukullam +author: juliakm +ms.date: 05/28/2025 +monikerRange: '= azure-devops' +"recommendations": "true" +ai-usage: ai-assisted +ms.custom: peer-review-program +--- + +# Use scripts to automate Azure Resource Manager with workload identity service connections + +[!INCLUDE [version-lt-eq-azure-devops](../../includes/version-eq-azure-devops.md)] + +Learn how to use scripts to create Azure Resource Manager service connections with workload identity in Azure Pipelines. Scripts ensure consistency, efficiency, and repeatability when setting up service connections, reducing the risk of human error. They save time, especially when creating multiple connections or deploying to different environments. These scripts can also be integrated into an automation process to scale and better manage large deployments. + +Using scripts as part of an automation process helps enforce security policies and compliance requirements by ensuring service connections use the correct permissions and configurations. It also serves as documentation for the setup process. + +## Prerequisites + +| **Product** | **Requirements** | +|---|---| +| **Azure DevOps** | - 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. +| **Azure** | An [Azure subscription](https://azure.microsoft.com/free/).
      **Permissions:**
           - To create a role assignment in Azure: you must have *User Access Administrator* or *Role Based Access Control Administrator* permissions, or higher. These roles allow you to manage access and assign roles necessary for creating identities. For more information, see [Azure built-in roles](/azure/role-based-access-control/built-in-roles).| +| **Entra** | **Permissions:**
           - To create an app registration in Microsoft Entra: [App registration delegation](/entra/identity/role-based-access-control/delegate-app-roles#restrict-who-can-create-applications) should be enabled or you should have the *Application Developer* role. For more information, see [Microsoft Entra built-in roles](/entra/identity/role-based-access-control/permissions-reference#application-developer).
      Instead of creating an app registration in Entra, you can also create a managed identity in Azure.| + +## Process + +### Constraints + +- In automation, `"creationMode": "Manual"` should be used when creating service connections that need a Microsoft Entra identity. Significant Microsoft Entra privileges would be required to have Azure DevOps create all objects on behalf of the caller, therefore Azure DevOps doesn't support the use of `"creationMode": "Automatic"` for non-user principals. Instead, end-to-end automation should create each object (identity, service connection, credential, role assignment) individually. +- Workload identity federation defines a bi-directional relationship between the identity and service connection. As a result, objects need to be created in a certain order and the federated credential can only be created after the service connection is created. + +### Command execution order + +This table provides an overview of the key properties exchanged between the creation commands of each object. Dependencies on output determine the order of execution. + +| Step | Input | Output | +|-----------------------------------------------|------------------------|-------------------------| +| Create identity in Microsoft Entra or Azure | `tenantId` | `appId`, `principalId` | +| Create service connection in Azure DevOps | `appId` | `workloadIdentityFederationIssuer`, `workloadIdentityFederationSubject` | +| Create federated credential in Microsoft Entra or Azure | `appId`, `workloadIdentityFederationIssuer`, `workloadIdentityFederationSubject` | | +| Create role assignment in Azure | `principalId` | | + +## 1. Sign in with Azure CLI + +The following commands use the Azure CLI. Sign in to the intended tenant: + +```azurecli +az login --tenant TENANT_ID +``` + +Learn more in [Authenticate to Azure using Azure CLI](/cli/azure/authenticate-azure-cli). + +## 2. Create identity + +Create an identity using managed identity or an app registration. + +#### [Managed identity](#tab/managed-identity) + +Create a managed identity with `az identity create`. + +```azurecli +az identity create --name MyIdentity --resource-group MyResourceGroup --query '{clientId:clientId,principalId:principalId}' +``` + +Example output: + +```json +{ + "clientId": "00001111-aaaa-2222-bbbb-3333cccc4444", + "principalId": "aaaaaaaa-bbbb-cccc-1111-222222222222" +} +``` + +A managed identity creates a service principal in Microsoft Entra. The object ID of the service principal is also called `principalId`. Use the service principal later to assign RBAC roles. The `appId` is used to create the service connection in Azure DevOps. + +Learn more in [az identity create](/cli/azure/identity#az-identity-create). + +#### [App registration](#tab/app-registration) + +Create an app registration using `az ad sp create-for-rbac`. + +```azurecli +az ad sp show --id $(az ad sp create-for-rbac -n appreg-for-rbac --create-password false -o tsv --query appId) --query '{appId:appId,principalId:id}' +``` + +Example output: + +```json +{ + "appId": "00001111-aaaa-2222-bbbb-3333cccc4444", + "principalId": "aaaaaaaa-bbbb-cccc-1111-222222222222" +} +``` + +This command creates an app and a service principal in Microsoft Entra and retrieves its `appId` and `principalId`. The object ID of the service principal is also called `principalId`. You'll use the service principal later to assign RBAC roles. The `appId` is used to create the service connection in Azure DevOps. The `--create-password false` flag ensures no password is created for the service principal. + +For more information, see [az ad sp create-for-rbac](/cli/azure/ad/sp#az-ad-sp-create-for-rbac). + +--- + +## 3. Create a service connection + +This example uses the [Azure DevOps Azure CLI extension](/azure/devops/cli) and a configuration file to create the service connection. This configures the identity created in a new Azure service connection. The `servicePrincipalId` authorization parameter is populated with the `appId` of the identity. + +You'll need an `appId` to use as input. + +The first code snippet is a configuration file, `ServiceConnectionGeneric.json`. + +> [!div class="tabbedCodeSnippets"] +```json +{ + "data": { + "subscriptionId": "SUBSCRIPTION_ID", + "subscriptionName": "My Azure Subscription", + "environment": "AzureCloud", + "scopeLevel": "Subscription", + "creationMode": "Manual" + }, + "name": "MyNewServiceEndpoint", + "type": "AzureRM", + "url": "https://management.azure.com/", + "authorization": { + "parameters": { + "tenantid": "aaaabbbb-0000-cccc-1111-dddd2222eeee", + "serviceprincipalid": "00001111-aaaa-2222-bbbb-3333cccc4444" + }, + "scheme": "WorkloadIdentityFederation" + }, + "isShared": false, + "isReady": true, + "serviceEndpointProjectReferences": [ + { + "projectReference": { + "id": "c7e5f0b3-71fa-4429-9fb3-3321963a7c06", + "name": "TestProject" + }, + "name": "MyNewServiceEndpoint" + } + ] +} +``` + +```azurecli +az devops service-endpoint create -service-endpoint-configuration ./ServiceConnectionGeneric.json --query authorization.parameters +``` + +`az devops service-endpoint create` automates creating a service connection in Azure DevOps using `ServiceConnectionGeneric.json`. The output includes authorization parameters you'll use in future steps. + +Example output: + +```json +{ + "serviceprincipalid": "00001111-aaaa-2222-bbbb-3333cccc4444", + "tenantid": "aaaabbbb-0000-cccc-1111-dddd2222eeee", + "workloadIdentityFederationIssuer": "https://login.microsoftonline.com/aaaabbbb-0000-cccc-1111-dddd2222eeee/v2.0", + "workloadIdentityFederationIssuerType": "EntraID", + "workloadIdentityFederationSubject": "" +} +``` + +For more information about this command, see [Azure DevOps CLI service endpoint](/azure/devops/cli/service-endpoint). + +## 4. Create a federated identity credential + +Create a federated credential using the `workloadIdentityFederationIssuer` and `workloadIdentityFederationSubject` output from the __Create a service connection__ step. + +#### [Managed identity](#tab/managed-identity) + +```azurecli +az identity federated-credential create --name fic-for-sc + --identity-name MyIdentity + --resource-group MyResourceGroup + --issuer "https://login.microsoftonline.com/TENANT_ID/v2.0" + --subject "" + --subscription MSI_SUBSCRIPTION_ID +``` + +`az identity federated-credential create` links a federated identity credential to a managed identity, enabling the managed identity to authenticate with Microsoft Entra ID using the provided subject claim. + +> [!TIP] +> Add a line continuation character (Bash: backslash, PowerShell: backquote) at the end of any lines that don't complete the command. + +The managed identity doesn't have to be created in the same subscription that it's granted to access in the [Create role assignment step](#5-create-role-assignment). + +For more information about this command, see [az identity federated-credential create](/cli/azure/identity/federated-credential#az-identity-federated-credential-create). + +#### [App registration](#tab/app-registration) + +```json +{ + "name": "fic-for-sc", + "issuer": "https://login.microsoftonline.com/aaaabbbb-0000-cccc-1111-dddd2222eeee/v2.0", + "subject": "", + "audiences": [ + "api://AzureADTokenExchange" + ] +} +``` + +```azurecli +az ad app federated-credential create --id APP_ID --parameters credential.json +``` + +`az ad app federated-credential create` links a federated identity credential to an app registration, enabling the application to authenticate with the specified identity provider using the details in the `credential.json` file. + +For more information about this command, see [az ad app federated-credential create](/cli/azure/ad/app/federated-credential#az-ad-app-federated-credential-create). + +--- + +## 5. Create role assignment + +Add a role assignment to your managed identity or app registration with `az role assignment create`. For available roles, see [Azure built-in roles](/azure/role-based-access-control/built-in-roles). The assignee of the role is the service principal associated with the app registration or managed identity. A service principal is identified by its ID, also called `principalId`. The `principalId` is in the output of the __Create identity__ command. + +```azurecli +az role assignment create --role Contributor --scope /subscriptions/SUBSCRIPTION_ID --assignee-object-id PRINCIPAL_ID --assignee-principal-type ServicePrincipal +``` + +`az role assignment create --role Contributor` command assigns the Contributor role to a service principal at the subscription level. This allows the service principal to manage resources within the specified subscription. + +For more information on this command, see [az role assignment create](/cli/azure/role/assignment#az-role-assignment-create). \ No newline at end of file diff --git a/docs/pipelines/release/azure-key-vault.md b/docs/pipelines/release/azure-key-vault.md index f7db0f5a668..0a90dbbf67a 100644 --- a/docs/pipelines/release/azure-key-vault.md +++ b/docs/pipelines/release/azure-key-vault.md @@ -1,10 +1,13 @@ --- 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 +monikerRange: '>= azure-devops' +ms.custom: + - devx-track-azurecli + - arm2024 + - sfi-image-nochange "recommendations": "true" --- @@ -12,7 +15,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 +28,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**, selecting **Grant access permission to all pipelines** lets all pipelines use this connection. This option isn't recommended. Instead, [authorize each pipeline individually to use the service connection](../library/service-endpoints.md#authorize-pipelines). + +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. In **Security**, selecting **Grant access permission to all pipelines** lets all pipelines use this connection. This option isn't recommended. Instead, [authorize each pipeline individually to use the service connection](../library/service-endpoints.md#authorize-pipelines). - :::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 +282,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 +393,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 +407,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..32ddd4a1d6f 100644 --- a/docs/pipelines/release/caching.md +++ b/docs/pipelines/release/caching.md @@ -1,11 +1,11 @@ --- title: Pipeline caching -description: Improve pipeline performance by caching files, like dependencies, between runs +description: Improve pipeline performance by caching files such as dependencies between runs. ms.assetid: B81F0BEC-00AD-431A-803E-EDD2C5DF5F97 -ms.topic: conceptual +ms.topic: overview ms.custom: devx-track-dotnet, devx-track-js, devx-track-python ms.manager: adandree -ms.date: 10/03/2022 +ms.date: 04/23/2025 monikerRange: azure-devops --- @@ -13,69 +13,80 @@ monikerRange: azure-devops [!INCLUDE [version-eq-azure-devops](../../includes/version-eq-azure-devops.md)] -Pipeline caching can help reduce build time by allowing the outputs or downloaded dependencies from one run to be reused in later runs, thereby reducing or avoiding the cost to recreate or redownload the same files again. Caching is especially useful in scenarios where the same dependencies are downloaded over and over at the start of each run. This is often a time consuming process involving hundreds or thousands of network calls. +Pipeline caching can help reduce build time by reusing downloaded dependencies from previous runs, avoiding the need to recreate or redownload the same files. This is particularly helpful in scenarios where the same dependencies are downloaded repeatedly at the start of each run. This is often a time consuming process involving hundreds or thousands of network calls. -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 most effective when the time required to restore and save the cache is less than the time it takes to regenerate the files. However, in some cases, caching may not provide performance benefits and could even negatively impact build time. It's important to evaluate your specific scenario to determine whether caching is the right approach. -Caching is currently supported in CI and deployment jobs, but not classic release jobs. +> [!NOTE] +> Pipeline caching is not supported for Classic release pipelines. -### When to use artifacts versus caching +## When to use pipeline artifacts versus pipeline caching -Pipeline caching and [pipeline artifacts](../artifacts/pipeline-artifacts.md) perform similar functions but are designed for different scenarios and shouldn't be used interchangeably. +Pipeline caching and [pipeline artifacts](../artifacts/pipeline-artifacts.md) perform similar functions but are intended for different scenarios and shouldn't be used interchangeably. -* **Use pipeline artifacts** when you need to take specific files produced in one job and share them with other jobs (and these other jobs will likely fail without them). +- **Use pipeline artifacts**: when you need to take specific files produced by one job and share them with other jobs (and those other jobs would likely fail without them). -* **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). +- **Use pipeline caching**: when you want to improve build time by reusing files from previous runs (and not having those 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. - -## Cache task: how it works +> Pipeline caching and pipeline artifacts are available at no cost for all tiers (free and paid). See [Artifacts storage consumption](../../artifacts/artifact-storage.md) for more details. -Caching is added to a pipeline using the [Cache task](/azure/devops/pipelines/tasks/reference/cache-v2). This task works like any other task and is added to the `steps` section of a job. +## Self-hosted agent requirements -When a cache step is encountered during a run, the task restores the cache based on the provided inputs. If no cache is found, the step completes and the next step in the job is run. +The following executables must be located in a folder listed in the `PATH` environment variable. Note that these requirements apply only to self-hosted agents, as hosted agents come preinstalled with the necessary software. -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**. +| Archive software / Platform | Windows | Linux | Mac | +|-----------------------------|------------ |--------- |----------| +|GNU Tar | Required | Required | No | +|BSD Tar | No | No | Required | +|7-Zip | Recommended | No | No | -> [!NOTE] -> Caches are immutable, meaning that once a cache is created, its contents cannot be changed. +## Cache task: How it works -### Configure the Cache task +Caching is added to a pipeline by adding the [Cache task](/azure/devops/pipelines/tasks/reference/cache-v2) to the `steps` section of a job. -The [Cache task](/azure/devops/pipelines/tasks/reference/cache-v2) has two required arguments: *key* and *path*: +During pipeline execution, when a cache step is encountered, the task attempts to restore the cache based on the provided inputs. If no cache is found, the step completes, and the next step in the job is executed. -- **path**: the path of the folder to cache. Can be an absolute or a relative path. Relative paths are resolved against `$(System.DefaultWorkingDirectory)`. +Once all steps in the job have run successfully, 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] -> You can use [predefined variables](../build/variables.md) to store the path to the folder you want to cache, however wildcards are not supported. +> Caches are immutable. Once a cache is created, its content cannot be modified. -- **key**: should be set to the identifier for the cache you want to restore or save. Keys are composed of a combination of string values, file paths, or file patterns, where each segment is separated by a `|` character. +## Configure the Cache task -* **Strings**:
      -Fixed value (like the name of the cache or a tool name) or taken from an environment variable (like the current OS or current job name) +The [Cache task](/azure/devops/pipelines/tasks/reference/cache-v2) has two required arguments: *path* and *key*: -* **File paths**:
      -Path to a specific file whose contents will be hashed. This file must exist at the time the task is run. Keep in mind that *any* key segment that "looks like a file path" will be treated like a file path. In particular, this includes segments containing a `.`. This could result in the task failing when this "file" doesn't exist. - > [!TIP] - > To avoid a path-like string segment from being treated like a file path, wrap it with double quotes, for example: `"my.key" | $(Agent.OS) | key.file` +1. **path**: The path to the folder you want to cache. This can be an absolute or relative path. Relative paths are resolved against `$(System.DefaultWorkingDirectory)`. -* **File patterns**:
      -Comma-separated list of glob-style wildcard pattern that must match at least one file. For example: - * `**/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 + > [!TIP] + > You can use [predefined variables](../build/variables.md) to store the path to the folder you want to cache. However, wildcards are not supported. -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. +2. **key**: This defines the identifier for the cache you want to restore or save. The key is composed of a combination of string values, file paths, or file patterns, with each segment separated by a `|` character. -Relative file paths or file patterns are resolved against `$(System.DefaultWorkingDirectory)`. + - **Strings**:
      + A fixed value (such as the cache name or a tool name), or taken from an environment variable (like the current OS or job name). + + - **File paths**:
      + The path to a specific file whose contents will be hashed. The file must exist at the time the task is run. Any segment that resembles a file path is treated as such, so be cautious, especially when using segments containing `.`, as this may lead to "file doesn't exist" failures. -**Example**: + > [!TIP] + > To avoid a path-like string segment from being treated like a file path, wrap it with double quotes, for example: `"my.key" | $(Agent.OS) | key.file` + + - **File patterns**:
      + A comma-separated list of glob-style wildcard patterns that must match at least one file. Examples: + + - `**/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 those in the *bin* directory. + +The contents of any file identified by a file path or file pattern are hashed to generate a dynamic cache key. This is useful when your project has files that uniquely identify what’s being cached. For instance, files like `package-lock.json`, `yarn.lock`, `Gemfile.lock`, or `Pipfile.lock` are often referenced in a cache key, as they represent a unique set of dependencies. Relative file paths or patterns are resolved against `$(System.DefaultWorkingDirectory)`. -Here's an example showing how to cache dependencies installed by Yarn: +- **Example**: + +The following example shows how to cache Yarn packages: ```yaml variables: - YARN_CACHE_FOLDER: $(Pipeline.Workspace)/.yarn + YARN_CACHE_FOLDER: $(Pipeline.Workspace)/s/.yarn steps: - task: Cache@2 @@ -90,30 +101,25 @@ steps: - script: yarn --frozen-lockfile ``` -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. +In this example, the cache key consists of three parts: a static string ("yarn"), the OS the job is running on (since the cache is unique per operating system), and the hash of the `yarn.lock` file (which uniquely identifies the dependencies). -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" because 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 will likely reside 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`. +If you're not using `checkout: self`, ensure you update the `YARN_CACHE_FOLDER` variable to point to the location of `.yarn` in your repository. -#### 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. +### Use restore keys -#### Required software on self-hosted agent +`restoreKeys` allows you to query multiple exact keys or key prefixes. It's used as a fallback when the specified `key` doesn't yield a hit. A restore key searches for a key by prefix and returns the most recently created cache entry. This is helpful when the pipeline cannot find an exact match but still wants to use a partial cache hit. -| Archive software / Platform | Windows | Linux | Mac | -|--------|-------- |------ |-------| -|GNU Tar | Required| Required | No | -|BSD Tar | No | No | Required | -|7-Zip | Recommended | No | No | +To specify multiple restore keys, list them on separate lines. The order in which the restore keys are tried is from top to bottom. -The above executables need to be in a folder listed in the PATH environment variable. Keep in mind that the hosted agents come with the software included, this is only applicable for self-hosted agents. +- **Example**: -**Example**: - -Here's an example of how to use restore keys by Yarn: +Here's an example of how to use restore keys to cache Yarn packages: ```yaml variables: @@ -132,71 +138,83 @@ steps: - script: yarn --frozen-lockfile ``` -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. +In this example, the cache task first attempts to restore the specified key. If the key doesn't exist in the cache, it then tries the first restore key: `yarn | $(Agent.OS)`. This searches for any cache keys that exactly match or start with this prefix. + +A prefix match can occur if the hash of the `yarn.lock` file has changed. For example, if the cache contains the key `yarn | $(Agent.OS) | old-yarn.lock` (where `old-yarn.lock` has a different hash than the current `yarn.lock`), this restore key would result in a partial cache hit. + +If the first restore key doesn't yield a match, the next restore key (`yarn`) This will search for any cache key that starts with `yarn`. For prefix matches, the restore process returns the most recently created cache entry. > [!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 include multiple caching tasks, and there's no storage limit for caching. Jobs and tasks within the same pipeline can access and share the same cache. + +## Use restore condition + +In some scenarios, you may want to conditionally execute steps based on whether the cache was successfully restored. For example, you can skip a step that installs dependencies if the cache was restored. This can be achieved using the `cacheHitVar` argument. + +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` if a restore key yields a partial cache hit, and `false` if no cache is found. You can then reference this variable in a [step condition](../process/conditions.md) or within a script. + +Here’s an example where the `install-deps.sh` step is skipped when the cache is restored: + +```yaml +steps: +- task: Cache@2 + inputs: + key: mykey | mylockfile + restoreKeys: mykey + path: $(Pipeline.Workspace)/mycache + cacheHitVar: CACHE_RESTORED + +- script: install-deps.sh + condition: ne(variables.CACHE_RESTORED, 'true') + +- script: build.sh +``` ## 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 is stored within a logical container called a *scope*. Scopes act as a security boundary that guarantees: + +- Jobs from one pipeline can’t access caches from a different pipeline. -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. +- Jobs building pull requests can read caches from the target branch (for the same pipeline), but can't write (create) caches in the target branch's scope. -### CI, manual, and scheduled runs +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. + +#### CI, manual, and scheduled runs | Scope | Read | Write | |---------------------------------------------------|------|-------| | Source branch | Yes | Yes | -| main branch (default branch) | Yes | No | +| `main` branch | Yes | No | +| `master` branch | Yes | No | -### Pull request runs +#### Pull request runs | Scope | Read | Write | |---------------------------------------------------|------|-------| | 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 +#### Pull request fork runs | Branch | Read | Write | |---------------------------------------------------|------|-------| | 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. - -## 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 the following example, the `install-deps.sh` step is skipped when the cache is restored: - -```yaml -steps: -- task: Cache@2 - inputs: - key: mykey | mylockfile - restoreKeys: mykey - path: $(Pipeline.Workspace)/mycache - cacheHitVar: CACHE_RESTORED +> 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. -- script: install-deps.sh - condition: ne(variables.CACHE_RESTORED, 'true') - -- script: build.sh -``` +## Examples -## Bundler +### [Bundler](#tab/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 to set the [path](https://bundler.io/v2.3/man/bundle-config.1.html) where Bundler looks for Gems. **Example**: @@ -209,13 +227,13 @@ 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++) +### [Ccache](#tab/ccache) [Ccache](https://ccache.dev/) is a compiler cache for C/C++. To use Ccache in your pipeline make sure `Ccache` is installed, and optionally added to your `PATH` (see [Ccache run modes](https://ccache.dev/manual/3.7.1.html#_run_modes)). Set the `CCACHE_DIR` environment variable to a path under `$(Pipeline.Workspace)` and cache this directory. @@ -232,19 +250,19 @@ 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. -## Docker images +### [Docker](#tab/docker) -Caching Docker images dramatically reduces the time it takes to run your pipeline. +Caching Docker images can significantly reduce the time it takes to run your pipeline. ```yaml variables: @@ -258,9 +276,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,10 +301,32 @@ 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**: -## Golang + ```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 + ``` + +### [Go](#tab/golang) For Golang projects, you can specify the packages to be downloaded in the *go.mod* file. If your `GOCACHE` variable isn't already set, set it to where you want the cache to be downloaded. @@ -307,7 +347,7 @@ steps: ``` -## Gradle +### [Gradle](#tab/gradle) Using Gradle's [built-in caching support](https://docs.gradle.org/current/userguide/build_cache.html) can have a significant impact on build time. To enable the build cache, set the `GRADLE_USER_HOME` environment variable to a path under `$(Pipeline.Workspace)` and either run your build with `--build-cache` or add `org.gradle.caching=true` to your `gradle.properties` file. @@ -321,7 +361,7 @@ steps: - task: Cache@2 inputs: key: 'gradle | "$(Agent.OS)" | **/build.gradle.kts' # Swap build.gradle.kts for build.gradle when using Groovy - restoreKeys: | + restoreKeys: | # The fallback keys if the primary key fails (Optional) gradle | "$(Agent.OS)" gradle path: $(GRADLE_USER_HOME) @@ -340,14 +380,12 @@ steps: displayName: Gradlew stop ``` -- **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 (such as a branch), it can't be updated. This means that if you use a fixed key value, all subsequent builds for the same branch won't be able to update the cache—even if the cache contents have changed. If you use a fixed key, be sure to specify the `restoreKeys` input as a fallback option. -## Maven +### [Maven](#tab/maven) -Maven has a local repository where it stores downloads and built artifacts. To enable, set the `maven.repo.local` option to a path under `$(Pipeline.Workspace)` and cache this folder. +Maven uses a local repository to store downloaded dependencies and built artifacts. To enable caching, set the `maven.repo.local` option to a path under `$(Pipeline.Workspace)` and cache this folder. **Example**: @@ -378,10 +416,11 @@ If you're using a [Maven task](/azure/devops/pipelines/tasks/reference/maven-v3) mavenOptions: '-Xmx3072m $(MAVEN_OPTS)' ``` -## .NET/NuGet +### [.NET/NuGet](#tab/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 +439,13 @@ steps: displayName: Cache NuGet packages ``` -## Node.js/npm +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`. -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. +### [Npm](#tab/npm) -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. +There are different ways to enable caching in a Node.js project, but the recommended approach 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 installation, npm checks this directory first (by default), which can reduce or eliminate network calls to the public npm registry or a private registry. + +Because the default path to npm's shared cache directory [varies across platforms](https://docs.npmjs.com/misc/config#cache), it's recommended to override the `npm_config_cache` environment variable and set it to a path under `$(Pipeline.Workspace)`. This also ensures the cache is accessible from both container and noncontainer jobs. **Example**: @@ -420,18 +461,16 @@ steps: npm | "$(Agent.OS)" path: $(npm_config_cache) displayName: Cache npm - -- script: npm ci ``` If your project doesn't have a `package-lock.json` file, reference the `package.json` file in the cache key input instead. > [!TIP] -> Because `npm ci` deletes the `node_modules` folder to ensure that a consistent, repeatable set of modules is used, you should avoid caching `node_modules` when calling `npm ci`. +> Since `npm ci` deletes the `node_modules` folder to ensure a consistent and repeatable set of modules, avoid caching `node_modules` when using `npm ci`. -## Node.js/Yarn +### [Yarn](#tab/yarn) -Like with npm, there are different ways to cache packages installed with Yarn. The recommended way is to cache Yarn's [shared cache folder](https://yarnpkg.com/lang/en/docs/cli/cache/). This directory is managed by Yarn and contains a cached version of all downloaded packages. During install, Yarn checks this directory first (by default) for modules, which can reduce or eliminate network calls to public or private registries. +Like npm, Yarn offers several ways to cache installed packages. The recommended approach is to cache Yarn's [shared cache folder](https://yarnpkg.com/lang/en/docs/cli/cache/). This directory is managed by Yarn and stores cached versions of all downloaded packages. During installation, Yarn checks this directory first (by default), which can reduce or even eliminate network calls to public or private registries. **Example**: @@ -452,7 +491,7 @@ steps: - script: yarn --frozen-lockfile ``` -## Python/Anaconda +### [Python/Anaconda](#tab/python) Set up your pipeline caching with Anaconda environments: @@ -504,7 +543,7 @@ steps: condition: eq(variables.CONDA_CACHE_RESTORED, 'false') ``` -## PHP/Composer +### [PHP/Composer](#tab/php) For PHP projects using Composer, override the `COMPOSER_CACHE_DIR` [environment variable](https://getcomposer.org/doc/06-config.md#cache-dir) used by Composer. @@ -527,34 +566,44 @@ steps: - script: composer install ``` +--- + ## Known issues and feedback -If you're experiencing issues setting up caching for your pipeline, check the list of [open issues](https://github.com/microsoft/azure-pipelines-tasks/labels/Area%3A%20PipelineCaching) in the :::no-loc text="microsoft/azure-pipelines-tasks"::: repo. If you don't see your issue listed, [create](https://github.com/microsoft/azure-pipelines-tasks/issues/new?labels=Area%3A%20PipelineCaching) a new one and provide the necessary information about your scenario. +If you're having trouble setting up caching in your pipeline, check the list of [open issues](https://github.com/microsoft/azure-pipelines-tasks/labels/Area%3A%20PipelineCaching) in the :::no-loc text="microsoft/azure-pipelines-tasks"::: repo. If you don't see your issue listed, [create](https://github.com/microsoft/azure-pipelines-tasks/issues/new?labels=Area%3A%20PipelineCaching) a new one and provide the necessary information about your scenario. ## Q&A -### Q: Can I clear a cache? +#### Q: Can I clear a cache? -A: Clearing a cache is currently not supported. However you can add a string literal (such as `version2`) to your existing cache key to change the key in a way that avoids any hits on existing caches. For example, change the following cache key from this: +A: Clearing a cache is not supported. However, you can avoid hits on existing caches by adding a string literal (such as `version2`) to your cache key. For example, change the following cache key from this: ```yaml key: 'yarn | "$(Agent.OS)" | yarn.lock' ``` -to this: +To this: ```yaml key: 'version2 | yarn | "$(Agent.OS)" | yarn.lock' ``` -### Q: When does a cache expire? +#### Q: When does a cache expire? A: Caches expire after seven days of no activity. -### Q: When does the cache get uploaded? +#### Q: When does the cache get uploaded? + +A: A cache is created from your specified `path` and uploaded after the last step of the job. See the [example](#configure-the-cache-task) for more details. + +#### Q: Is there a limit on the size of a cache? + +A: There's no enforced limit on the size of individual caches or the total cache size within an organization. + +## Related content -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. +- [Publish and download pipeline artifacts](../artifacts/pipeline-artifacts.md) -### Q: Is there a limit on the size of a cache? +- [Secure your Azure Pipelines](../security/overview.md) -A: There's no enforced limit on the size of individual caches or the total size of all caches in an organization. +- [Manage permissions](../policies/permissions.md) diff --git a/docs/pipelines/release/configure-workload-identity.md b/docs/pipelines/release/configure-workload-identity.md new file mode 100644 index 00000000000..308f3da63d1 --- /dev/null +++ b/docs/pipelines/release/configure-workload-identity.md @@ -0,0 +1,325 @@ +--- +title: Set a Resource Manager workload identity service connection +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' +ms.custom: + - devx-track-arm-template + - arm2024 + - sfi-image-nochange +"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, selecting **Grant access permission to all pipelines** lets all pipelines use this connection. This option isn't recommended. Instead, [authorize each pipeline individually to use the service connection](../library/service-endpoints.md#authorize-pipelines). + +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, selecting **Grant access permission to all pipelines** lets all pipelines use this connection. This option isn't recommended. Instead, [authorize each pipeline individually to use the service connection](../library/service-endpoints.md#authorize-pipelines). + +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..0cc8add94a2 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 @@ -4,15 +4,14 @@ description: DevOps CI CD - Deploy to Azure VMs using deployment groups in Azure ms.topic: tutorial ms.date: 05/26/2020 monikerRange: '<= azure-devops' +ms.custom: sfi-image-nochange --- # Deploy to Azure VMs using deployment groups in Azure 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 + 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 +44,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 +108,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 +128,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..5dcc7eab5bd 100644 --- a/docs/pipelines/release/deployment-groups/index.md +++ b/docs/pipelines/release/deployment-groups/index.md @@ -1,114 +1,126 @@ --- -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 in 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: 05/22/2025 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, each have a deployment agent installed. Deployment groups typically represent environments such as *Development, *Test*, or *Production*. Each physical or virtual machine in the deployment group communicates with Azure Pipelines to coordinate deployment tasks. Deployment groups differ 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. +Deployment groups give you a flexible way to manage and monitor your deployment targets. You can define the security context and runtime environment for agents, assign roles and permissions to team members, and get real-time visibility into deployments with live logs for each server. You can also use tags to target specific machines, making deployments more precise and efficient. -With 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. +> [!NOTE] +> Deployment groups are only available in Classic release pipelines. -* 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. +| **Product** | **Requirements** | +|--------------------|--------------------| +| **Azure DevOps** | - An Azure DevOps [organization](../../../organizations/accounts/create-organization.md).
      - An Azure DevOps [project](../../../organizations/projects/create-project.md).
      - Administrator permissions on a Windows or Linux machine to install and configure the deployment agent. | ## 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. Sign in to your Azure DevOps organization, and navigate to your project. -1. From within your project, select **Pipelines** > **Deployment groups**. +1. In your project, select **Pipelines**, then select **Deployment groups**. - :::image type="content" source="media/pipelines-deployment-groups.png" alt-text="Access deployment groups"::: +1. On the **Deployment groups** page, select **New**. If this is your first deployment group, select **Add a deployment group**. + +1. Enter a **Deployment group name** and then select **Create**. -1. Select **Add a deployment group**. +1. On the next screen, select **Windows** or **Linux** for the **Type of target to register**. A registration script is generated. - :::image type="content" source="media/add-deployment-groups.png" alt-text="Add new deployment groups"::: - -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. Select **Use a personal access token in the script for authentication**, then select **Copy script to the clipboard**. - :::image type="content" source="media/generated-script.png" alt-text="Create a deployment group - generated script"::: +1. Save the copied script to run on all the target machines in your deployment group. -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"::: + :::image type="content" source="media/generated-script.png" alt-text="A screenshot displaying how to create a deployment group in Azure Pipelines."::: -After setting up your target servers, the script should return the following message: `Service vstsagent.{organization-name}.{computer-name} started successfully`. +## Register target servers -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. +To register each target server in the deployment group: -> [!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. +1. Sign in to the machine using an account with administrator permissions, and run the copied script. For Windows machines, use an elevated PowerShell command prompt. -:::image type="content" source="media/update-targets-pools.png" alt-text="A screenshot showing how to update targets in deployment pools."::: +1. When prompted to add tags (can be used to target deployments to specific servers in a [deployment group job](../../process/deployment-group-phases.md)), enter Y, then provide one or more tags. Tags are case insensitive, limited to 256 characters each, and there's no limit to the number of tags you can use. +1. Once setup is complete, the script should return the following message: -## Set up agents on deployment groups + ``` + Service vstsagent.{organization-name}.{computer-name} started successfully. + ``` -Every target server in the deployment group requires a deployment agent. You can install an agent on your target servers in three different ways: +## Install and upgrade agents -- By running the [generated script](#create-a-deployment-group) from the **Deployment Groups** tab. +Every target server in the deployment group requires a deployment agent. The generated registration script for target servers installs an agent. Alternatively, you can install agents using one of the following methods: -- 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. +- For 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. -- 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. +- Use the [AzureResourceGroupDeploymentV2 task](./howto-provision-deployment-group-agents.md#use-the-azureresourcegroupdeploymentv2-task) in a release pipeline to dynamically create and register deployment group agents. -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. +See [Provision agents for deployment groups](howto-provision-deployment-group-agents.md) for more details. + +To upgrade deployment agents to the latest version without redeploying, go to the **Deployment groups** page, select the **More actions** ellipsis next to your deployment group, and choose **Update targets**. See [Agents](../../agents/agents.md) for more details. :::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 -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. +A deployment pool is a collection of target servers available across your entire Azure DevOps organization. To create or manage deployment pools, you must have Project Collection Administrator permissions. -:::image type="content" source="media/deployment-groups-release-summary.png" alt-text="Deployment groups release logs"::: +When you create a new deployment pool, you can automatically provision corresponding deployment groups in selected projects or across all projects in the organization. These deployment groups share the same target servers as the deployment pool. -## Share a deployment group with other projects +To upgrade the agent version on all servers in a deployment pool, go to **Deployment pools**, select the **More actions** ellipsis next to the pool, and choose **Update targets**. -Deployment groups can be shared with other projects in the same organization. Follow the steps below to provision your deployment group for other projects: +:::image type="content" source="media/update-targets-pools.png" alt-text="A screenshot displaying how to update targets in deployment pools."::: -1. From within your project, select **Pipelines** > **Deployment groups**. +## Share deployment groups -1. Select your deployment group and then select **Manage**. +You can share deployment groups with other projects in your Azure DevOps organization. To make a deployment group available to other projects: - :::image type="content" source="media/manage-deployment-group.png" alt-text="Manage deployment groups"::: +1. Sign in to your Azure DevOps organization, and navigate to your project. -1. Select a project from the list and then select **Save**. +1. Select **Pipelines** > **Deployment groups**. Select your deployment group and then select **Manage**. - :::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/manage-deployment-group.png" alt-text="A screenshot displaying the details page of a deployment group."::: -1. You will now notice that there is a new Deployment Group in the project you just included. +1. In the list of projects, select the ones you want to share the deployment group with, and then select **Save**. + + :::image type="content" source="media/deployment-group-share-with-project.png" alt-text="A screenshot displaying how to share with other projects."::: - :::image type="content" source="media/shared-deployment-group.png" alt-text="Shared new deployment group"::: +1. After saving, the selected projects will see the shared deployment group listed under **Deployment groups**. + + :::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. +You can configure your environment to automatically deploy the last successful release when new target servers are added to a deployment group: + +1. Sign in to your Azure DevOps organization, and navigate to your project. + +1. Select **Pipelines** > **Releases**, then select your release pipeline. + +1. Select the post deployment icon to open the **Post-deployment conditions** screen, and 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="A screenshot displaying how to enable the Auto redeploy trigger."::: -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. +## Related content -:::image type="content" source="../media/deployment-group-add-targets.png" alt-text="Automatically deploy to new target servers"::: +- [Release triggers](../triggers.md) -## Related articles +- [Manage permissions](../../policies/permissions.md) -- [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) +- [Deploy to Azure VMs using deployment groups](deploying-azure-vms-deployment-groups.md) \ No newline at end of file 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/release/from-classic-pipelines.md b/docs/pipelines/release/from-classic-pipelines.md new file mode 100644 index 00000000000..03fd66445bf --- /dev/null +++ b/docs/pipelines/release/from-classic-pipelines.md @@ -0,0 +1,79 @@ +--- +title: Migrate your Classic pipeline to YAML +titleSuffix: Azure Pipelines +description: Learn how to migrate from Classic pipelines to YAML. +ms.subservice: azure-devops-pipelines-migrate +ms.topic: quickstart +ms.date: 06/26/2025 +monikerRange: azure-devops +--- + +# Migrate your Classic pipeline to YAML + +[!INCLUDE [version-eq-azure-devops](../../includes/version-eq-azure-devops.md)] + +Azure Pipelines lets you manage your CI/CD process as code, making it easier to track changes, compare versions, annotate, and more. + +When you convert a Classic pipeline, you’ll end up with two pipelines: a new YAML pipeline and the original Classic one, which can then be retired. Your Classic pipeline's run history remains in the Classic pipeline. + +> [!NOTE] +> You can only export a YAML file from a Classic pipeline created using the classic build designer. If you don’t see an option to export to YAML or JSON, your pipeline likely doesn’t support exporting. Classic release pipelines don’t support YAML export, you’ll need to export each task individually. + +## Prerequisites + +| **Product** | **Requirements** | +|--------------------|--------------------| +| **Azure** | - An Azure account with an active [subscription](https://azure.microsoft.com/free/?WT.mc_id=A261C142F). | +| **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.
      - A working Classic pipeline. | + +## Create a sample YAML pipeline + +Follow these steps to create a starter YAML pipeline, which you’ll later update with code exported from the Classic UI editor: + +1. Sign in to your organization, and navigate to your project. + +1. Select **Pipelines**, and then select **New pipeline**. + + :::image type="content" source="media/pipelines-new-pipeline.png" alt-text="A screenshot displaying how to create a new pipeline."::: + +1. Select your source code location either **GitHub** or **Azure Repos Git**, and then select your repository. + + :::image type="content" source="media/source-code-location.png" alt-text="A screenshot displaying source code locations."::: + +1. On the **Configure your pipeline page**, select the **Starter pipeline**. + + :::image type="content" source="media/select-pipeline-template.png" alt-text="A screenshot displaying the available pipeline templates."::: + +1. Select **Save and run**, and then enter your commit message. Select **Commit directly to the main branch**, and then select **Save and run** once more. This will start a new run and commit the yaml pipeline to your repository. + + :::image type="content" source="media/commit-save-run.png" alt-text="A screenshot displaying how to save and run a new yaml pipeline."::: + +## Export a Classic pipeline to YAML + +1. Sign in to your Azure DevOps organization, and navigate to your project. + +1. Select **Pipelines** > **Pipelines**. + +1. Find your Classic pipeline, select the ellipses (...) next to it, 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="A screenshot displaying how to export a Classic pipeline to YAML."::: + +1. Open the downloaded YAML file in your code editor. + +1. If your Classic pipeline used variables defined in the Classic UI editor, you’ll need to redefine them either in the YAML file or in the pipeline settings. See [Define variables](../process/variables.md) for more details. + +1. Review any `cron` schedules in your YAML file. YAML schedules use UTC by default, while Classic pipelines use your organization’s local time zone. See [Configure schedules for pipelines](../process/scheduled-triggers.md) for more details. + +1. Use the **Task Assistant** (the pane on the right side of the editor) to help you add or modify steps in your YAML file. + + :::image type="content" source="media/task-assistant-yaml.png" alt-text="A screenshot displaying how to configure pipeline tasks with the Task Assistant."::: + +1. Select **Save and run** once you're done. + +## Related content + +- [YAML vs Classic Pipelines](../get-started/pipelines-get-started.md#feature-availability) + +- [Customize your pipeline](../customize-pipeline.md) + +- [YAML pipeline editor](../get-started/yaml-pipeline-editor.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). + + > [!IMPORTANT] + > For United States inbound connections, make sure to add the IP ranges for **all** US regions. + +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..9ef9dade37a 100644 --- a/docs/pipelines/release/key-vault-in-own-project.md +++ b/docs/pipelines/release/key-vault-in-own-project.md @@ -1,9 +1,12 @@ --- -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 + - sfi-image-nochange "recommendations": "true" --- @@ -11,45 +14,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 +52,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 +67,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 +258,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..80293c6bb71 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/) 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..c3df7d92544 --- /dev/null +++ b/docs/pipelines/security/secrets.md @@ -0,0 +1,114 @@ +--- +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. +- **[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](/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. +- [**Personal access tokens (PATs)**](../../organizations/accounts/use-personal-access-tokens-to-authenticate.md): Keep PAT duration short and choose the minimal permissions needed during creation. + +## 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 to 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..7a3b13272d1 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 + displayName: 'Install SqlServer module if not present' inputs: - filename: Sqlcmd - arguments: '-S $(ServerFqdn) -U $(AdminUser) -P $(AdminPassword) -d $(DatabaseName) -i $(SQLFile)' + 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) diff --git a/docs/pipelines/targets/azure-stack.md b/docs/pipelines/targets/azure-stack.md index 68a57bdb89f..28ae95124c5 100644 --- a/docs/pipelines/targets/azure-stack.md +++ b/docs/pipelines/targets/azure-stack.md @@ -3,11 +3,11 @@ 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" +ms.custom: sfi-image-nochange --- # 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..5adf1e60ea8 100644 --- a/docs/pipelines/targets/create-virtual-network.md +++ b/docs/pipelines/targets/create-virtual-network.md @@ -1,22 +1,20 @@ --- -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 monikerRange: '<= azure-devops' +ms.custom: sfi-image-nochange --- # Create a virtual network isolated environment for build-deploy-test scenarios [!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 +43,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 +201,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 +239,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 +336,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..3b8db9b166a 100644 --- a/docs/pipelines/tasks/file-matching-patterns.md +++ b/docs/pipelines/tasks/file-matching-patterns.md @@ -1,10 +1,10 @@ --- 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 +ai-usage: ai-assisted ms.assetid: 8A92C09C-3EE2-48EF-A2C0-3B2005AACFD7 -ms.date: 12/13/2019 +ms.date: 06/24/2025 monikerRange: '<= azure-devops' --- @@ -19,12 +19,19 @@ File and directory names are compared to patterns to include (or sometimes exclu You can build up complex behavior by stacking multiple patterns. See [fnmatch](http://man7.org/linux/man-pages/man3/fnmatch.3.html) for a full syntax guide. +- [Match characters](#match-characters) +- [Extended globbing](#extended-globbing) +- [Comments](#comments) +- [Exclude patterns](#exclude-patterns) +- [Escaping](#escaping) +- [Slash](#slash) + ### Match characters Most characters are used as exact matches. What counts as an "exact" match is platform-dependent: the Windows filesystem is case-insensitive, so the pattern "ABC" would match a file called "abc". -On case-sensitive filesystems, that pattern and name would not match. +On case-sensitive filesystems, that pattern and name wouldn't match. The following characters have special behavior. @@ -34,41 +41,57 @@ The following characters have special behavior. * `**` recursive wildcard. For example, `/hello/**/*` matches all descendants of `/hello`. ### Extended globbing -* `?(hello|world)` - matches `hello` or `world` zero or one times + +* `?(hello|world)` - matches `hello` or `world` zero times or one time * `*(hello|world)` - zero or more occurrences * `+(hello|world)` - one or more occurrences * `@(hello|world)` - exactly once * `!(hello|world)` - not `hello` or `world` -Note, extended globs cannot span directory separators. For example, `+(hello/world|other)` is not valid. +> [!NOTE] +> Extended globs can't span directory separators. For example, `+(hello/world|other)` isn't valid. ### Comments + Patterns that begin with `#` are treated as comments. ### Exclude patterns + Leading `!` changes the meaning of an include pattern to exclude. You can include a pattern, exclude a subset of it, and then re-include a subset of that: this is known as an "interleaved" pattern. Multiple `!` flips the meaning. See examples. -You must define an include pattern before an exclude one. See examples. +You must define an include pattern before an exclude pattern. See examples. ### Escaping + + Wrapping special characters in `[]` can be used to escape literal glob characters in a file name. For example the literal file name `hello[a-z]` can be escaped as `hello[[]a-z]`. ### Slash + `/` is used as the path separator on Linux and macOS. Most of the time, Windows agents accept `/`. Occasions where the Windows separator (`\`) must be used are documented. ## Examples +- [Basic pattern examples](#basic-pattern-examples) +- [Asterisk examples](#asterisk_examples) +- [Question mark examples](#question_mark_examples) +- [Character set examples](#character_set_examples) +- [Recursive wildcard examples](#recursive-wildcard-examples) +- [Exclude pattern examples](#exclude-pattern-examples) +- [Double exclude examples](#doubleexcl_examples) +- [Folder exclude examples](#folder-exclude-examples) + ### Basic pattern examples

      Asterisk examples

      -**Example 1:** Given the pattern `*Website.sln` and files: +**Example 1:** Given the pattern `*Website.sln`, and the following files: ``` ConsoleHost.sln ContosoWebsite.sln @@ -97,7 +120,7 @@ FabrikamWebsite/FabrikamWebsite.proj

      Question mark examples

      -**Example 1:** Given the pattern `log?.log` and files: +**Example 1:** Given the pattern `log?.log`, and the following files: ``` log1.log log2.log @@ -111,7 +134,7 @@ log2.log log3.log ``` -**Example 2:** Given the pattern `image.???` and files: +**Example 2:** Given the pattern `image.???`, and the following files: ``` image.tiff image.png @@ -125,7 +148,7 @@ image.ico

      Character set examples

      -**Example 1:** Given the pattern `Sample[AC].dat` and files: +**Example 1:** Given the pattern `Sample[AC].dat`, and the following files: ``` SampleA.dat SampleB.dat @@ -138,7 +161,7 @@ SampleA.dat SampleC.dat ``` -**Example 2:** Given the pattern `Sample[A-C].dat` and files: +**Example 2:** Given the pattern `Sample[A-C].dat`, and the following files: ``` SampleA.dat SampleB.dat @@ -152,7 +175,7 @@ SampleB.dat SampleC.dat ``` -**Example 3:** Given the pattern `Sample[A-CEG].dat` and files: +**Example 3:** Given the pattern `Sample[A-CEG].dat`, and the following files: ``` SampleA.dat SampleB.dat @@ -174,28 +197,47 @@ SampleG.dat #### Recursive wildcard examples -Given the pattern `**/*.ext` and files: +Given the pattern `**/*.ext`, and the following files: ``` sample1/A.ext sample1/B.ext sample2/C.ext sample2/D.not ``` + The pattern would match: + ``` sample1/A.ext sample1/B.ext sample2/C.ext ``` +*The following example was generated by Copilot. 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).* + +The `**/*.ext` glob pattern is a powerful recursive pattern used in many file systems and tools (like `bash`, `zsh`, `Python glob`, etc.) to match all files ending in `.ext` in the current directory and all subdirectories, no matter how deeply nested. + +Here are some example paths that would match `**/*.ext`: + +- `sample1/A.ext` +- `sample1/B.ext` +- `sample2/C.ext` +- `sample2/subdir1/D.ext` +- `sample2/subdir1/subdir2/E.ext` +- `sample3/F.ext` +- `sample3/subdir3/G.ext` +- `sample3/subdir3/subdir4/H.ext` + +The `**` part means any number of directories (including zero), and `*.ext` means any file ending in `.ext`. + ### Exclude pattern examples -Given the pattern: +Given the following pattern, and the following files: ``` * !*.xml ``` -and files: + ``` ConsoleHost.exe ConsoleHost.pdb @@ -212,15 +254,15 @@ Fabrikam.dll Fabrikam.pdb ``` -

      Double exclude

      +

      Double exclude examples

      -Given the pattern: +Given the following pattern, and the following files: ``` * !*.xml !!Fabrikam.xml ``` -and files: + ``` ConsoleHost.exe ConsoleHost.pdb @@ -238,14 +280,14 @@ Fabrikam.pdb Fabrikam.xml ``` -

      Folder exclude

      +#### Folder exclude examples -Given the pattern: +Given the following pattern, and the following files: ``` ** !sample/** ``` -and files: + ``` ConsoleHost.exe ConsoleHost.pdb 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..d2dc08944ae 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' --- @@ -43,17 +43,19 @@ Slide the On/Off button to **On**. > ![Screenshot of Test Management, Flaky test detection enabled, System detection.](media/flaky-test-management/system-detection.png) The default setting for all projects is to use flaky tests for troubleshooting. +> [!Note] +> Switching between systems is inherently disruptive, as all flakiness history stored in Azure DevOps is erased during the transition. ### Flaky test detection Flaky test management supports system and custom detection. -- **System detection**: The in-product flaky detection uses test rerun data. The detection is via **VSTest task** rerunning of failed tests capability or retry of stage in the pipeline. You can select specific pipelines in the project for which you would like to detect flaky tests. +- **System detection**: Azure DevOps has a built-in mechanism for detecting flaky tests. This involves rerunning failed tests within the same pipeline execution. If a test case fails initially but passes on a rerun, it is marked as flaky. This detection is tightly coupled with the **VSTest** task, which reruns failed tests within the same task execution. Another method involves rerunning failed jobs in the pipeline (manually by clicking on "rerun failed jobs" in any pipeline run). If a test passes in the rerun, it is marked as flaky. > [!Note] > Once a test is marked as flaky, the data is available for all pipelines for that branch to assist with troubleshooting in every pipeline. -- **Custom detection**: You can integrate your own flaky detection mechanism with Azure Pipelines and use the reporting capability. With custom detection, you need to update the test results metadata for flaky tests. For details, see [Test Results, Result Meta Data - Update REST API](/rest/api/azure/devops/testresults/result-meta-data/update). +- **Custom detection**: This approach allows external systems to integrate their own logic for detecting flaky tests and rely on Azure DevOps for consistent tracking and management. Communication with Azure DevOps is enabled using the [Result Meta Data - Update](/rest/api/azure/devops/testresults/result-meta-data/update) API. The API requires a Test Case Reference ID, a flag indicating whether the test is considered flaky, and the repository branch where the flakiness was observed. User should be able to get the Test Case Reference Id from the [Get Test Result By Id](/rest/api/azure/devops/testresults/results/get-test-result-by-id) API. Once this information is sent to Azure DevOps, the system stores and propagates the flakiness status for that test case in subsequent pipeline runs. After a test is marked as flaky, Azure DevOps will continue to treat it as such until it is manually unmarked. > [!div class="mx-imgBorder"] > ![Screenshot of Test Management, Flaky test detection enabled, Custom detection.](media/flaky-test-management/custom-detection.png) 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..3c8baaf1b7c 100644 --- a/docs/pipelines/test/requirements-traceability.md +++ b/docs/pipelines/test/requirements-traceability.md @@ -3,11 +3,14 @@ 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.author: jeom +author: raviLiftr ms.date: 07/01/2020 monikerRange: '<= azure-devops' +ms.custom: + - continuous-test + - cross-service + - sfi-image-nochange --- # Requirements traceability @@ -16,19 +19,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 +36,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 +61,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 +86,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 +111,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 +120,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 +130,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 +143,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..cfaf129f247 100644 --- a/docs/pipelines/test/review-continuous-test-results-after-build.md +++ b/docs/pipelines/test/review-continuous-test-results-after-build.md @@ -3,11 +3,14 @@ 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.author: jeom +author: raviLiftr ms.date: 10/06/2021 monikerRange: '<= azure-devops' +ms.custom: + - continuous-test + - cross-service + - sfi-image-nochange --- # Review test results @@ -16,10 +19,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 +32,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 +64,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 +92,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 +132,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 +146,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 +171,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 +182,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 +195,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 +214,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 +235,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 +259,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..0422b978345 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 **TIA\_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..d9d2920d60e 100644 --- a/docs/pipelines/test/ui-testing-considerations.md +++ b/docs/pipelines/test/ui-testing-considerations.md @@ -1,13 +1,13 @@ --- 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.date: 04/25/2024 monikerRange: '<= azure-devops' +ms.custom: + - continuous-test + - sfi-image-nochange --- # UI testing considerations @@ -15,17 +15,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 +29,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 +46,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 +68,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 +114,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 +168,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..51d62b25258 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 + - 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: 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 - 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: Use scripts to automate Azure Resource Manager service connections + displayName: service connection, service principal, Azure resource manager, azure + href: release/automate-service-connections.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: Deployment groups (Classic) + items: + - name: Use deployment groups in Classic releases + 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: Ecosystems examples + 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: 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: 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: 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 - 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 Classic pipelines to YAML + 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..86c8cfa4cfe 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: 04/25/2025 monikerRange: '<= azure-devops' author: steved0x --- @@ -15,336 +14,157 @@ 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 +:::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."::: -::: 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). +## View logs -> [!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" +Select the error message to view logs for the task that didn't complete. -* [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) +:::image type="content" source="./media/error-message.png" alt-text="Screenshot of a task error message on pipeline run summary page."::: -> [!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) +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`. -::: moniker-end +:::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."::: -::: moniker range="< azure-devops" +You can view the raw log for the task by choosing **View raw log**, and you can search the log using **Find**. -* [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/view-raw-log.png" alt-text="Screenshot of log view options in Azure DevOps."::: +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). +:::moniker range=">= azure-devops-2020" -### Parallel job limits - no available agents or you have hit your free limits - -::: 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 +## Error analysis page -::: moniker range="< azure-devops" +Troubleshooting assistance is available using the **Error analysis** page. Move the mouse over the error information line and choose the **View analysis** icon. -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**. +:::moniker-end - ![View queued jobs](../media/troubleshooting/agent-pools-jobs.png) +:::moniker range="azure-devops" - 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. +:::image type="content" source="./media/pipeline-error-analysis-icon.png" alt-text="Screenshot of view analysis icon on pipeline run summary page."::: -### 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**. +:::moniker-end - ![Agent status](../media/troubleshooting/agents-online.png) +:::moniker range=">= azure-devops-2020 < azure-devops" - This page shows all the agents currently online/offline and in use. You can also add additional agents to the pool from this page. +:::image type="content" source="./media/pipeline-error-analysis-icon-server.png" alt-text="Screenshot of view analysis icon for Azure DevOps Server."::: -::: moniker-end +:::moniker-end -### Demands that don't match the capabilities of an agent +:::moniker range=">= azure-devops-2020" -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. +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. -To check the capabilities and demands specified for your agents and pipelines, see [Capabilities](../agents/agents.md#capabilities). +:::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. -> [!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/task-details.png" alt-text="Screenshot of task details from error analysis."::: -::: moniker-end +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 range="< azure-devops" +:::moniker-end -### TFS agent connection issues +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. -* [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) +## Common issues -``` -Testing agent connection. -VS30063: You are not authorized to access http://:8080/tfs -``` +* [This pipeline needs permission to access a resource before this run can continue](#this-pipeline-needs-permission-to-access-a-resource-before-this-run-can-continue) +* [Job time-out](#job-time-out) +* [Issues downloading code](#issues-downloading-code) +* [My pipeline is failing on a command-line step such as MSBUILD](#my-pipeline-is-failing-on-a-command-line-step-such-as-msbuild) +* [File or folder in use errors](#file-or-folder-in-use-errors) +* [Intermittent or inconsistent MSBuild failures](#intermittent-or-inconsistent-msbuild-failures) +* [Process stops responding](#process-stops-responding) +* [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) -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" -![is TFS anonymous authentication enabled](../media/troubleshooting/iis-tfs-anonymous-authentication-enabled.png) +### Task insights for failed pipeline runs - - +Azure DevOps provides a **Task Insights for Failed Pipeline Runs** setting, that when enabled, provides pop-up notifications of build failures with a link to view a report. -#### Agent lost communication +:::image type="content" source="../get-started/media/task-insights.png" alt-text="Screenshot of task insights metrics."::: -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. -``` +To configure this setting, navigate to [Preview features](../../project/navigation/preview-features.md), find **Task Insights for Failed Pipeline Runs**, and choose the desired setting. -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="../get-started/media/task-insights-setting.png" alt-text="Screenshot of task insights for failed pipeline runs setting."::: -* 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. +### Notifications for failed runs -#### TFS Job Agent not started +Azure DevOps includes build-in notifications for failed pipeline runs. To enable notifications: -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. +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**. -#### Misconfigured notification URL (1.x agent version) +:::image type="content" source="media/notification-settings.png" alt-text="Screenshot of notifications in project settings."::: -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-end -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. +### This pipeline needs permission to access a resource before this run can continue -::: moniker-end +If your pipeline doesn't seem to start, or you receive an error message like `This pipeline needs permission to access a resource before this run can continue`, check to see if the pipeline is waiting for an authorization to run by a resource, like a service connection or agent pool. -::: moniker range="azure-devops" +1. [Go to the pipeline](../create-first-pipeline.md#view-and-manage-your-pipelines) and manually start a run. +1. The message **This pipeline needs permission to access a resource before this run can continue** appears. Select **View** next to the message. +1. On the **Waiting for review** screen, select **Permit**, and on the confirmation screen, select **Permit** again. -### Check Azure DevOps status for a service degradation +This action explicitly adds the pipeline as an authorized user of the resource. -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). +There are two ways to authorize pipelines to access your agent pool. -::: moniker-end +* [Authorize specific pipelines](#authorize-specific-pipelines) - Individually authorize specific pipelines from an Azure DevOps project to run in the pool. +* [Configure open access](#configure-open-access) - Configure an agent pool at project level to be available for all pipelines in that project. - +#### Authorize specific pipelines -## Pipeline fails to complete +You can individually authorize specific pipelines to run in an agent pool by following the procedure in the previous section when you receive a message like `This pipeline needs permission to access a resource before this run can continue`. -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). +You can also manually add and remove pipelines from the authorized list by performing the following procedure. This procedure is performed at the project level in your Azure DevOps organization. -* [Job time-out](#job-time-out) -* [Issues downloading code](#issues-downloading-code) -* [My pipeline is failing on a command-line step such as MSBUILD](#my-pipeline-is-failing-on-a-command-line-step-such-as-msbuild) -* [File or folder in use errors](#file-or-folder-in-use-errors) -* [Intermittent or inconsistent MSBuild failures](#intermittent-or-inconsistent-msbuild-failures) -* [Process stops responding](#process-stops-responding) -* [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) +1. In Azure DevOps, go to **Project settings**, **Agent pools**, choose your self-hosted pool, and choose **Security**. +1. Choose **+** to add a pipeline to the authorized list. +1. Choose **X** **(Revoke access)** to remove a pipeline from the authorized list. -:::moniker range="azure-devops" +#### Configure open access -### Task insights for failed pipeline runs +Some resources allow you to configure **Open access** so that each new pipeline definition doesn't require explicit authorization. -Azure DevOps provides a **Task Insights for Failed Pipeline Runs** setting, that when enabled, provides pop-up notifications of build failures with a link to view a report. +Configuring **Open access** requires [Project administrator](../../organizations/security/permissions.md#project-level-groups) permissions. -:::image type="content" source="../get-started/media/task-insights.png" alt-text="Screenshot of task insights metrics."::: +To configure **Open access** for agent pools: -To configure this setting, navigate to [Preview features](../../project/navigation/preview-features.md), find **Task Insights for Failed Pipeline Runs**, and choose the desired setting. +1. In Azure DevOps, go to **Project settings**, **Agent pools**, choose your self-hosted pool, and choose **Security**. +1. Choose **More actions**, **Open access**, to enable open access, and choose **Open access** again to confirm. +1. To revoke open access, choose **Restrict permission**. -:::image type="content" source="../get-started/media/task-insights-setting.png" alt-text="Screenshot of task insights for failed pipeline runs setting."::: +To review whether **Open access** is available for other [resource types](../process/resources.md#resource-authorization-in-yaml-pipelines), see [Manage security in Azure Pipelines](../policies/permissions.md) and search for **Open access**. -:::moniker-end +For more information on **Open access** for agent pools, see [Set pipeline permissions for an individual agent pool](../policies/permissions.md#set-pipeline-permissions-for-an-individual-agent-pool) and [Pipeline permissions](../agents/pools-queues.md#pipeline-permissions). ### 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 +173,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 +186,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 +205,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 +216,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 +269,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 +295,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 +312,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 +328,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 +340,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 +359,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 +373,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 +385,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 +408,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..bf1614e850a 100644 --- a/docs/project/navigation/mobile-work.md +++ b/docs/project/navigation/mobile-work.md @@ -1,131 +1,143 @@ --- -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 -ms.custom: Navigation +description: View and update work items from your mobile client using Azure DevOps. 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 +ms.custom: + - Navigation + - sfi-image-nochange --- -# 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..56b3e255d82 100644 --- a/docs/project/search/functional-package-search.md +++ b/docs/project/search/functional-package-search.md @@ -1,5 +1,5 @@ --- -title: Search packages +title: Search for packages across feeds titleSuffix: Azure Artifacts description: How to search for packages across all your feeds and in upstream sources in an Azure DevOps organization. ms.subservice: azure-devops-search @@ -8,42 +8,44 @@ ms.topic: how-to ms.author: chcomley author: chcomley monikerRange: 'azure-devops' -ms.date: 11/28/2022 +ms.date: 07/10/2025 --- -# Search packages across your feeds +# Search for 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 time-consuming, especially when you're managing multiple feeds, versions, and dependencies. In this article, you learn how to use Azure DevOps Code Search to perform functional package searches across all your feeds to help you locate your packages based on functionality, versions, or type. ## 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](../../artifacts/start-using-azure-artifacts.md#create-a-new-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 +Azure DevOps code search lets you search all feeds in your organization, regardless of the project you’re in. -1. Select the filter icon to show the filter panel. +1. Sign in to your Azure DevOps organization and navigate to your project (`https://dev.azure.com/{Your_Organization}/{Your_Project}`). - :::image type="content" source="media/shared/pkgsrch-results-filtericon.png" alt-text="Screenshot Showing the filter lists"::: +1. In the search bar, enter a term (for example, time) in the search box and press Enter. This returns any package with the term "time" in its name or description. -1. Select from the dropdown menus to search by feeds, views, or package types. +1. Select the **Package** tab to view all search results. Use the **Feeds**, **Views**, or **Type** dropdown menus to filter results by feed, feed view, or package type (for example, NuGet). - :::image type="content" source="media/shared/pkgsrch-results-filters.png" alt-text="Screenshot showing the filter panel options"::: + :::image type="content" source="media/shared/package-search-results-filters.png" alt-text="A screenshot displaying how to filter the package search results."::: -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). +> [!NOTE] +> The **Views** filter appears only when you select a single feed from the **Feeds** filter. -## Search using the REST API +## Search for packages 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. +The Azure DevOps REST API provides an endpoint that allows you to search for packages within a specific organization. The following example demonstrates how to construct the HTTP request and request body to search for the *react-calendar* npm package across all feeds in your organization. See [Fetch package search results](/rest/api/azure/devops/search/package-search-results/fetch-package-search-results) for more details. -#### Example +#### Example: ```Command -POST https://almsearch.dev.azure.com/ORGANIZATION_NAME/_apis/search/packagesearchresults?api-version=7.0 +POST https://almsearch.dev.azure.com/ORGANIZATION_NAME/_apis/search/packagesearchresults?api-version=7.1 ``` ```Request body @@ -58,23 +60,30 @@ POST https://almsearch.dev.azure.com/ORGANIZATION_NAME/_apis/search/packagesearc } ``` -## Search in upstream sources +## Search for packages in upstream sources + +Azure Artifacts upstream sources enable developers to consume packages from different feeds and public registries such as *NuGet.org*. Using Azure Artifacts, you can search for various types of packages in your upstream sources. + +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. -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. +1. Select **Search Upstream Sources** in the upper-right corner of the page. + +1. Choose a **Package type** and then enter the exact name in the **Package Name** text box. The package name is case sensitive and must be an exact match. + +1. Select **Search** to view a list of available versions for the package you searched. > [!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. +> Searching for packages in upstream sources from your feed is supported only in Azure DevOps services. ## 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 +## Related content + +- [Functional code search](functional-code-search.md) -- [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) +- [Functional work item search](functional-work-item-search.md) 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..6bf37379ab2 100644 --- a/docs/project/search/install-configure-search.md +++ b/docs/project/search/install-configure-search.md @@ -3,38 +3,36 @@ title: Install, configure Search titleSuffix: Azure DevOps description: Find installation and setup instructions for Code, Wiki & Work Item Search in Azure DevOps Server. ms.assetid: -ms.custom: engagement-fy23 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 +ms.custom: + - engagement-fy23 + - sfi-image-nochange --- # 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 +49,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 +148,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 +185,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 +202,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..83987963d40 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,138 +34,99 @@ 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) - -> [!NOTE] -> When you're executing scripts, ensure that you run the appropriate script for your Azure DevOps Server or TFS 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) -> * [TFS 2018 Update 2](https://github.com/Microsoft/Code-Search/tree/master/TFS_2018Update2) -> * [Azure DevOps Server and TFS 2018 Update 3](https://github.com/Microsoft/Code-Search/tree/master/TFS_2018Update3) +![Screenshot showing download script files for administration.](media/administration/script-filesv2.png) ### 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..1d5ebf8a8c4 100644 --- a/docs/project/wiki/about-readme-wiki.md +++ b/docs/project/wiki/about-readme-wiki.md @@ -1,149 +1,110 @@ --- -title: Share information with a project, repo, README, or Wiki +title: Share Information with Project, Repo, README, Wiki titleSuffix: Azure DevOps -description: Share information using a project, repo, README, or Wiki in Azure DevOps. +description: Use a README file or wiki to share information about your project or repository with your team or contributors in Azure DevOps. ms.subservice: azure-devops-wiki ms.custom: wiki, devdivchpfy22 ms.assetid: ms.author: chcomley author: chcomley ms.reviewer: gopinach -ms.topic: overview -ms.date: 07/06/2022 -monikerRange: '<= azure-devops' +ms.topic: concept-article +ms.date: 05/19/2025 +#customer intent: As an Azure DevOps developer, I want to explore options for sharing information about my project and Git repositories, so I can best support my project users and contributors. --- -# 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. +You can support your team and project contributors by using [Markdown](https://en.wikipedia.org/wiki/Markdown) to add rich formatting, tables, and images to your team project. The Markdown format enhances team project wiki pages, content you add to a dashboard, your team project README file, or other repository README files. -## Wiki +## Set up a project 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. +A team project wiki lets you share information about your project with other team members. When you set up a wiki from scratch, a new Git repository stores your Markdown (_.md_) files, images, attachments, and sequence of pages. The 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 +The following links describe the supported features for a team project wiki. -::: moniker range=">= azure-devops-2019" +:::row::: -The following features are supported for the team project wiki. + :::column span=""::: + **Create new wiki** -### Provision or create a wiki + - [Create new project wiki](wiki-create-repo.md) + - [Publish project code as wiki](publish-repo-to-wiki.md) + :::column-end::: -- [Create a wiki for your team project](wiki-create-repo.md) -- [Publish code as wiki](publish-repo-to-wiki.md) + :::column span=""::: + **Work with wiki content** -### Work with wiki content + - [Add and edit pages](add-edit-wiki.md) + - [View page history or revert](wiki-view-history.md) + - [Clone and update offline](wiki-update-offline.md) + - [Use keyboard shortcuts](../navigation/keyboard-shortcuts.md#wiki-keyboard-shortcuts) + - [Filter or print content](filter-print-wiki.md)
      (_Print feature might not be available in Firefox browser_) + :::column-end::: -- [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 + :::column span=""::: + **Format wiki content** -> [!NOTE] -> The print feature may not be available from the Firefox web browser. + - [Use Markdown format](markdown-guidance.md) + - [Define HTML tags](markdown-guidance.md#html) + - [Insert and resize images](markdown-guidance.md#images) + - [Link with hash tags (#)](markdown-guidance.md#link-work-items) + - [Attach files or artifacts](markdown-guidance.md#attach) + - [Use mathematical notation](markdown-guidance.md#math-notation) + - [Add Table of contents (TOC)](markdown-guidance.md#toc-wiki) + :::column-end::: -### Format wiki content +:::row-end::: -- [Markdown format](markdown-guidance.md) -- [HTML tags](wiki-markdown-guidance.md#html) -- [Insert and resize images](markdown-guidance.md#images) -- [Link to work items using #](wiki-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) +## Publish Git repositories to a wiki -::: moniker-end +Many teams document their code by using Markdown files, which they check in to the repository along with their code. While Git supports the maintenance and review of code documentation files by using the standard pull request process, these files can present challenges to consumers of the content. -::: 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 | - -::: moniker-end - -::: moniker range=">= azure-devops-2019" - -## Publish existing Git repositories to a wiki - -Many teams document their code using Markdown and check in these files along with the code. While Git supports the maintenance and review of such documentation along with standard pull requests, such files present a few challenges to consumers of the content. - -- Readers must often sift through many files and folders to find the content of interest. +- User must often sift through many files and folders to find the content of interest. - Content lacks organization and structure. There's no inherent page hierarchy to support readers. - Content versioning isn't supported. -- Searching through content relies on searching the codes rather than a search experience optimized for searching content. +- Searching through content relies on searching the code rather than a search experience optimized for searching content. -With the publish code as a wiki feature, you can publish one or more Git repositories defined in your team project to a wiki. This feature provides a way to maintain your content alongside your code base, and lets you selectively publish and update your content to a wiki. +With the **Publish code as wiki** feature, you can publish one or more Git repositories defined in your team project to a wiki. This feature provides a way to maintain your code documentation synchronously with your code base, and lets you selectively publish and update your documentation to a wiki. -There are significant differences between how you manage the content for a wiki that you provision for a team project versus wiki pages that you publish from a Git repository. For details, see [Publish a Git repo to a wiki](publish-repo-to-wiki.md). +There are significant differences between how you manage the content in a wiki for a team project versus wiki pages that you publish from a Git repository. For details, see [Publish a Git repo to a wiki](publish-repo-to-wiki.md). -::: moniker-end +## Enhance project content with Markdown -## Markdown +The Markdown format 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. -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. +You can use Markdown to provide guidance to your team in the following ways: -You can provide guidance to your team in the following places using Markdown: - -::: moniker range=">= azure-devops-2019" - - [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) +- [Code published as wiki](publish-repo-to-wiki.md) +- [Dashboard content](../../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) - -::: moniker-end +- [Pull requests](../../repos/git/pull-requests.md) -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 +## Add project README files -You can define a README file or multiple files for each repo or team project. Write your README in Markdown instead of plain text. +You can define a README file or multiple files for each repo or team project. Write your README in Markdown instead of plain text. Use README pages to orient contributors to specific information or locations within your project. -Use README pages to orient contributors to work within your project. Consider adding the following guidance: +Consider adding the following guidance: - Project focus - Prerequisites -- Setting up the environment +- Set up the environment - Tips for getting things done within the project - Purpose or use of specific files - Project-specific terms and acronyms - Workflow guidance about committing or uploading changes and adding branches - Project sponsors or contacts -Here are some great READMEs that use this format and speak to all audiences for reference and inspiration: +### README examples + +Here are some examples of project READMEs in GitHub that support all audiences for reference and inspiration: - [ASP.NET Core](https://github.com/aspnet/Home) - [Visual Studio Code](https://github.com/Microsoft/vscode) -- [Chakra Core](https://github.com/Microsoft/ChakraCore) +- [Chakra Core](https://github.com/Microsoft/ChakraCore) \ No newline at end of file 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..f709ee1ae65 100644 --- a/docs/project/wiki/add-edit-wiki.md +++ b/docs/project/wiki/add-edit-wiki.md @@ -1,98 +1,98 @@ --- -title: Add, edit, reorder, and manage wiki pages +title: Add, Edit, Reorder, and Manage Wiki Pages titleSuffix: Azure DevOps -description: Learn how to add, edit, reorder, and manage pages for your built-in project wiki in Azure DevOps. +description: Learn how to add, edit, reorder, and manage pages for your team project wiki in Azure DevOps. ms.subservice: azure-devops-wiki ms.custom: wiki, devx-track-azurecli, devdivchpfy22 ms.assetid: BD03B9EE-D4DC-4EDC-B0BF-5C11B34E14C9 ms.author: chcomley author: chcomley ms.reviewer: gopinach -ms.topic: quickstart +ms.topic: how-to monikerRange: '<= azure-devops' -ms.date: 07/06/2022 +ms.date: 06/03/2025 +#customer intent: As an Azure DevOps developer, I want to understand how to add, update, delete, and arrange pages for my team project wiki, so I can manage the wiki as needed. --- # Add and edit wiki pages [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -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. +After you set up a [wiki Git repository](./wiki-create-repo.md) for your team project, you can add a title for the wiki and page content. The Azure DevOps UI provides a side-by-side experience where you can edit pages and preview your changes as you work. -Learn how to do the following tasks: +In the **Edit** pane, you enter page content by using [Markdown format syntax](./markdown-guidance.md). You can also insert images, attachments, and links. As you make changes, the content updates in the **Preview** pane. Content with special formatting like headings, lists, links, and images display as rich-text in the **Preview** pane. -> [!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 +:::image type="content" source="media/wiki/wiki-edit.png" border="false" alt-text="Screenshot of the Wiki home page in Azure DevOps showing the side-by-side experience where you can Edit page content and Preview your changes at the same time." lightbox="media/wiki/wiki-edit.png"::: -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 edit the page, use the **Ctrl+S** keyboard shortcut to quickly save your work. You can also save your work with a custom revision message like "Added page links." This option is available on the **Save** :::image type="icon" source="../../media/icons/context-menu.png"::: dropdown menu: -> [!div class="mx-imgBorder"] -> ![Wiki home page](media/wiki/wiki-edit.png) +:::image type="content" source="media/wiki/wiki-save-with-message.png" alt-text="Screenshot that shows how to select the Save with revision message option in Azure DevOps."::: -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). +Other keyboard shortcuts are available. For more information, 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) +> [!NOTE] +> This article describes how to add and edit pages in a wiki created for a team project. If you want to add or edit pages to a wiki published from a Git repository, see [Publish a Git repository to a wiki](publish-repo-to-wiki.md). ::: moniker range="azure-devops" ## Wiki command-line tools -| 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 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" +You can use Azure DevOps CLI commands to manage your wiki content. The following table provides links to sections in this article that describe how to work with specific commands. -> [!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. +| Command | Description | +|---------|-------------| +| [az devops wiki show](#open-wiki) | Open the wiki and show the wiki home page. | +| [az devops wiki page show](/cli/azure/devops/wiki/page#az-devops-wiki-page-show) | Show a specific page in the wiki. | +| [az devops wiki page create](#add-a-wiki-page) | Add a new page to the wiki. | +| [az devops wiki page update](#edit-and-delete-wiki-pages) | Edit an existing page in the wiki. | +| [az devops wiki page delete](#delete-wiki-page) | Delete a page in the wiki. | ::: 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 is located. You can request access from your project administrator, as needed. | +| **Permissions** | Member of the **Contributors** group. | +| **Access levels** | At least **Basic** access. | +| **Tasks** | Prepare a [provisioned wiki](wiki-create-repo.md) for your project. | + + [!INCLUDE [temp](includes/open-wiki-hub.md)] - + ## Add a wiki page -#### [Browser](#tab/browser) +This section describes how to add a page to your wiki. You can work directly with the Azure DevOps UI in the browser or use the Azure DevOps CLI. -To add another page, choose **New page**. Or, to add a subpage, open the context menu of an existing page and select **Add subpage**. +### [Browser](#tab/browser) -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). +To add a new page to your wiki, you have two options. Start by selecting a page in the list, such as the home page. -> [!div class="mx-imgBorder"] -> ![Create wiki and first page](media/wiki/add-new-page.png) +- To add a page at the same level as the current page, select **New page** at the bottom of the Azure DevOps UI. -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). +- To add a subpage to the current page, select **More options** (**...**) > **Add subpage**. -#### [Azure DevOps CLI](#tab/azure-devops-cli) +:::image type="content" source="media/wiki/add-new-page.png" border="false" alt-text="Screenshot that shows how to add a New page or new subpage to a wiki in Azure DevOps." lightbox="media/wiki/add-new-page.png"::: + +You can also use keyboard shortcuts to add pages. Select the current page, and then add a new page by selecting **n** or add a subpage by selecting **c**. For more information, see [Keyboard shortcuts to manage wiki pages](../navigation/keyboard-shortcuts.md#wiki-keyboard-shortcuts). + +#### Page title and file name + +Enter a unique title for the page. The value is case-sensitive. The title is used as the file name for the page. In the file name, spaces in the page title are replaced by hyphens (`-`). For example, the page title "How to contribute" corresponds to the file name _How-to-contribute.md_. The fully qualified path to the file should be 235 characters or less. + +For other file name restrictions, see [Wiki Git repository files and file structure, File naming conventions](wiki-file-structure.md#file-naming-conventions). + +### [Azure DevOps CLI](#tab/azure-devops-cli) ::: moniker range="azure-devops" -To add a wiki page, enter the `az devops wiki page create` command. +You can add a wiki page with the `az devops wiki page create` command: > [!div class="tabbedCodeSnippets"] ```azurecli @@ -106,80 +106,100 @@ az devops wiki page create --path [--subscription] ``` -### Parameters +For more information, see [Get started with the Azure DevOps CLI](../../cli/index.md). -- **--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 -- **--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. +#### Parameters: Create page -::: moniker-end -[!INCLUDE [temp](../../includes/note-cli-supported-server.md)] -::: moniker range="azure-devops" +The following parameters are available for the `wiki page create` command: -### Examples +| Parameter | Required | Description | Note | +|------------------|:--------:|-------------|------| +| `--path` | Yes | The fully qualified path for the wiki page. | | +| `--wiki` | Yes | The name or ID of the wiki. | | +| `--comment` | No | A comment to use in the commit message of the file **Add** operation. When no comment is specified, the default value is applied: "Added a new page using Azure DevOps CLI." | | +| `--content` | No | The content for the wiki page provided inline with the command, such as `--content "Hello World"`. | If you specify the page content by using the `--file-path` parameter, this parameter is **Ignored**. | +| `--file-path` | No | The path to the file that contains the page content. | | +| `--encoding` | Maybe | The encoding type of the page content. Possible values: `ascii`, `utf-16be`, `utf-16le`, and `utf-8`. | This parameter supports the `--file-path` parameter. When the `--file-path` parameter _isn't_ specified, this parameter is **Ignored**. | +| `--project -p` | Maybe | The name or ID of the project. You can configure the default project by using the `az devops configure -d project=NAME_OR_ID` command. | When the project isn't configured by default or picked up by using the `git config` command, the parameter is **Required**. | -Create a new page with the path 'my page' in a wiki named 'myprojectwiki' with inline content. +For more information, see the Azure DevOps CLI [command reference](/cli/azure/devops/wiki#az-devops-wiki-show). + +#### Example: Add wiki page in the browser + +The following command creates a new page with the path "Get Started" in a wiki named "MyProjectwiki." The command specifies the wiki page content inline: > [!div class="tabbedCodeSnippets"] ```azurecli -az devops wiki page update --path 'my page' --wiki myprojectwiki --content "Hello World" +az devops wiki page update --path 'Get Started' --wiki MyProjectwiki --content "**Contributor Support**
      TODO: Add introduction" ``` -Update content of the page with path 'my page' in a wiki with content from a file. +#### Example: Update wiki page in the browser + +The following command updates an existing wiki page with content from another file. The wiki page location is set with the `--path 'Get Started'` parameter. The page content is obtained from the `--file-path ./get-started-content.txt` parameter. The encoding for the file is also specified. > [!div class="tabbedCodeSnippets"] ```azurecli -az devops wiki page update --path 'my page' --wiki myprojectwiki --file-path a.txt --encoding utf-8 +az devops wiki page update --path 'Get Started' --wiki MyProjectwiki --file-path get-started-content.txt --encoding utf-8 ``` ::: moniker-end [!INCLUDE [note-cli-not-supported](../../includes/note-cli-not-supported.md)] - * * * -### Wiki page title naming restrictions +### Page title and file name restrictions [!INCLUDE [temp](./includes/wiki-naming-conventions.md)] +## Set the wiki home page + +By default, the first page you add when you create a wiki is set as the wiki home page. You can change your wiki homepage if another page becomes more relevant. For more information, see [Reorder or move wiki pages](#reorder-or-move-wiki-pages). + + + ## Edit and delete wiki pages -#### [Browser](#tab/browser) +This section describes how to edit or delete a page in your wiki. You can work directly with the Azure DevOps UI in the browser or use the Azure DevOps CLI. -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. +### [Browser](#tab/browser) + +There are several ways to edit an existing wiki page in the browser: + +- Open the wiki page and select **Edit**. +- Open the wiki page and use the keyboard shortcut **e**. +- Select the wiki page in the page list, then select **More options** (**...**) > **Edit**. + +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**. +#### Edit in Repos for code wikis -> [!div class="mx-imgBorder"] -> ![Edit wiki page.](media/wiki/edit-in-repos.png) +When you publish code as a wiki, you can edit the wiki pages in the **Repos** hub. The same side-by-side editor experience is available with the Markdown toolbar formatting options. Select **Edit** > **Edit in Repos** to create a branch and continue editing: -> [!NOTE] -> If you have branch policies in your code wiki, use **Edit in Repos** to create a branch and continue editing. +:::image type="content" source="media/wiki/edit-in-repos.png" alt-text="Screenshot that shows how to select the Edit in Repos option in Azure DevOps."::: + +The **Edit in Repos** option is available only for code wikis that have branch policies enabled. If you don't see the option, it might be because your wiki isn't a code wiki or branch policies aren't enabled. For more information, 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. +#### Delete wiki page in the browser + +To delete a wiki page, select the wiki page in the page list, then select **More options** (**...**) > **Delete**. You can also select **Delete** from the right-click menu for the page. + +After you select **Delete**, confirm the delete in the dialog. > [!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 metadata for the page and any subpages attached to the page. -#### [Azure DevOps CLI](#tab/azure-devops-cli) +### [Azure DevOps CLI](#tab/azure-devops-cli) ::: moniker range="azure-devops" -### Edit wiki page - -To edit a wiki page, enter the `az devops wiki page update` command. +You can edit a wiki page with the `az devops wiki page update` command: > [!div class="tabbedCodeSnippets"] ```azurecli @@ -193,40 +213,45 @@ az devops wiki page update --path [--subscription] ``` -### Parameters +For more information, see [Get started with the Azure DevOps CLI](../../cli/index.md). -- **--path**: Required. Path of the wiki page. -- **--version -v**: Required. Version (ETag) of the file to edit. -- **--wiki**: Required. Name of ID of the wiki. -- **--comment**: Optional. Comment in the commit message of delete operation. -- **--file-path**: Optional. Path of the file input if the content is specified in the file. -- **--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`. +#### Parameters: Update page -::: moniker-end -[!INCLUDE [temp](../../includes/note-cli-supported-server.md)] -::: moniker range="azure-devops" +The following parameters are available for the `wiki page update` command: + +| Parameter | Required | Description | Note | +|------------------|:--------:|-------------|------| +| `--path` | Yes | The fully qualified path for the wiki page. | | +| `--wiki` | Yes | The name or ID of the wiki. | | +| `--version -v` | No | The version of the wiki page, which corresponds to the `ETag` entity tag value. | | +| `--comment` | No | A comment to use in the commit message of the file **Delete** operation. When no comment is specified, the default value is applied: "Updated page using Azure DevOps CLI." | | +| `--file-path` | No | The path to the file that contains the page content. | | +| `--project -p` | Maybe | The name or ID of the project. You can configure the default project by using the `az devops configure -d project=NAME_OR_ID` command. | When the project isn't configured by default or picked up by using the `git config` command, the parameter is **Required**. | +| `--subscription` | No | The name or ID of the subscription. You can configure the default subscription with the `az account set -s NAME_OR_ID` command. | | +For more information, see the Azure DevOps CLI [command reference](/cli/azure/devops/wiki#az-devops-wiki-show). -### Examples +#### Example: Update wiki page with inline content -Update content of the page with path 'my page' in a wiki named 'myprojectwiki' with inline content. +The following command updates the content for the "Get Started" page in a wiki named "MyProjectwiki." The command specifies the wiki page content inline: > [!div class="tabbedCodeSnippets"] ```azurecli -az devops wiki page update --path 'my page' --wiki myprojectwiki --content "Hello World" --version 4ae78ad5835cb7dd55072fe210c9ee7eb6d6413b +az devops wiki page update --path 'Get Started' --wiki MyProjectwiki --content "**Contributor Support**
      TODO: Add introduction" --version 1234abcd5678efgh2345ijkl6789mnop3456qrst ``` -Update content of page with path 'my page' in a wiki with content from a file. +#### Example: Update wiki page with file content + +The following command updates an existing wiki page with content from another file. The wiki page location is set with the `--path 'Get Started'` parameter. The page content is obtained from the `--file-path ./get-started-content.txt` parameter. The encoding for the file is also specified. > [!div class="tabbedCodeSnippets"] ```azurecli -az devops wiki page update --path 'my page' --wiki myprojectwiki --file-path a.txt --encoding utf-8 --version 4ae78ad5835cb7dd55072fe210c9ee7eb6d6413b +az devops wiki page update --path 'Get Started' --wiki MyProjectwiki --file-path ./get-started-content.txt --encoding utf-8 --version 1234abcd5678efgh2345ijkl6789mnop3456qrst ``` ### Delete wiki page -To delete a wiki page, enter the `az devops wiki page delete` command. +You can edit a wiki page with the `az devops wiki page delete` command: > [!div class="tabbedCodeSnippets"] ```azurecli @@ -239,56 +264,94 @@ az devops wiki page delete --path ``` -### Parameters +For more information, see [Get started with the Azure DevOps CLI](../../cli/index.md). -- **--path**: Required. Path of the wiki page. -- **--wiki**: Required. Name or ID of the wiki. -- **--comment**: Optional. Comment in the commit message of the delete operation. -- **--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. +#### Parameters: Delete page -[!INCLUDE [note-cli-not-supported](../../includes/note-cli-not-supported.md)] +The following parameters are available for the `wiki page delete` command: + +| Parameter | Required | Description | Note | +|------------------|:--------:|-------------|------| +| `--path` | Yes | The fully qualified path for the wiki page. | | +| `--wiki` | Yes | The name or ID of the wiki. | | +| `--comment` | No | A comment to use in the commit message of the file **Delete** operation. When no comment is specified, the default value is applied: "Deleted page using Azure DevOps CLI." | | +| `--project -p` | Maybe | The name or ID of the project. You can configure the default project by using the `az devops configure -d project=NAME_OR_ID` command. | When the project isn't configured by default or picked up by using the `git config` command, the parameter is **Required**. | +| `--subscription` | No | The name or ID of the subscription. You can configure the default subscription with the `az account set -s NAME_OR_ID` command. | | +| `--yes -y` | No | Indicates that you don't want the operation to prompt you for confirmation. | | -### Example +For more information, see the Azure DevOps CLI [command reference](/cli/azure/devops/wiki#az-devops-wiki-show). -Delete a wiki page with the path 'my wiki' in a wiki named 'myprojectwiki'. +#### Example: Delete wiki page + +The following command deletes the "Get Started" page in a wiki named "MyProjectwiki": > [!div class="tabbedCodeSnippets"] ```azurecli -az devops wiki page delete --path 'my wiki' --wiki 'myprojectwiki' +az devops wiki page delete --path 'Get Started' --wiki 'MyProjectwiki' ``` ::: moniker-end [!INCLUDE [note-cli-not-supported](../../includes/note-cli-not-supported.md)] - * * * -## Reorder a wiki page +## Reorder or move wiki pages -You can reorder pages within the wiki tree view to have pages appear in the order and hierarchy you want. You can drag-and-drop a page title in the tree view to do the following operations: +In the browser, you can reorder pages in the wiki tree view so the pages display in your preferred sequence. The default sequence is alphabetically by file name. You might change the sequence to reorder pages by article, category, or intended audience. -* Change the parent-child relationship of a page. -* Change the order of the page within the hierarchy. +You can use the drag-and-drop action on page titles in the tree view to complete the following tasks: -> [!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. +- **Move**: Change the page/sub-page relationship of a page. If you move a page within the wiki sequence, links to the page from other wiki pages might break. You can manually [fix these links](#fix-broken-links-after-page-moves) after moving the page. + +- **Reorder**: Change the order of a page within the wiki sequence. Reordering pages within the wiki sequence doesn't affect page links. + +### Fix broken links after page moves + +To fix a broken link after you move a page in the wiki sequence, follow these steps: + +1. Test the other pages in your wiki and look for links to the moved page. + + Check for error messages on the page or missing content. + +1. Open the page that has a broken link, select **Edit**, and go to the broken link in the page content. + + To find the broken link in the content, you can search for the name of the moved page, the original file path of the moved page, or the link text for the broken link. + +1. Update the broken link. The typical fix is to change the URL or path in the link to target the new location for the moved page. + +1. Save your changes to the page so the link updates. + +1. Open the updated page in the browser and test the link. Confirm it successfully opens the moved page. + +### Change order of top-level pages + +You can use keyboard shortcuts to reorder top-level pages in the wiki sequence. This action doesn't work for subpages. + +Select a page in the wiki page list and use the **CTRL + UP ARROW** or **CTRL + DOWN ARROW** shortcut to move the page within the sequence. The change applies immediately. + +### Change page/sub-page order + +You can also change the page/sub-page order for any page in the wiki sequence. + +1. Select the page that you want to move in the wiki page list. + +1. Select **More options** (**...**) > **Move**, which opens the **Move page** dialog. + +1. In the **Move page** dialog, select the page to serve as the new _parent_ page. -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. + :::image type="content" source="media/wiki/wiki-move-page.png" border="false" alt-text="Screenshot that shows how to move a wiki page so it becomes a subpage of another page in the sequence." lightbox="media/wiki/wiki-move-page.png"::: -> [!div class="mx-imgBorder"] -> ![Move wiki page in the hierarchy](media/wiki/wiki-move-page.png) +1. After you select the new parent page, the system scans for any potential broken links based on the page move. It reports the links that need to be adjusted: -For a complete list of keyboard shortcuts, see [Keyboard shortcuts to manage wiki pages](wiki-keyboard-shortcuts.md). + :::image type="content" source="media/wiki/wiki-fix-affected-links.png" border="false" alt-text="Screenshot that shows how to have the system adjust any page links caused by a page move in the wiki sequence." lightbox="media/wiki/wiki-fix-affected-links.png"::: -## Make a page the wiki home page +1. Select the **Update affected links in pages and work items (recommended)** option and then select **Move** to complete the page move. -By default, the first page you add when you create a wiki is set as the wiki home page. You can change your wiki homepage if another page becomes more relevant by dragging and dropping the page to the top of the tree. +For a complete list of keyboard shortcuts, see [Keyboard shortcuts to manage wiki pages](../navigation/keyboard-shortcuts.md#wiki-keyboard-shortcuts). -## Next steps +## Related content -> [!div class="nextstepaction"] -> [View wiki page history and revert](wiki-view-history.md) +- [View wiki page history and revert](wiki-view-history.md) +- [Compare provisioned vs. published wiki](provisioned-vs-published-wiki.md) +- [Use wiki Markdown guidance](markdown-guidance.md) \ No newline at end of file diff --git a/docs/project/wiki/create-embed-wit-from-wiki.md b/docs/project/wiki/create-embed-wit-from-wiki.md index a134583822d..3b359d89066 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-work-items). ## 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..91b95304114 100644 --- a/docs/project/wiki/includes/open-wiki-hub.md +++ b/docs/project/wiki/includes/open-wiki-hub.md @@ -1,22 +1,25 @@ --- ms.topic: include +ms.date: 06/02/2025 --- ## Open the Wiki +You can open and view the wiki page for your team project from Azure DevOps in the browser or use the Azure DevOps CLI. + #### [Browser](#tab/browser) -Connect to your project using a [supported web browser](/azure/devops/server/compatibility#supported-browsers) and choose **Wiki**. +Connect to your project by using a [supported web browser](/azure/devops/server/compatibility#supported-browsers) and select **Wiki**: -:::image type="content" source="../media/open-wiki-vert-brn.png" alt-text="Screenshot showing highlighted Wiki menu selection."::: +:::image type="content" source="../media/open-wiki-overview-page.png" border="false" alt-text="Screenshot of a wiki open in the browser and showing the wiki overview page." lightbox="../media/open-wiki-overview-page.png"::: -If you need to switch your team project, choose :::image type="icon" source="../../../media/icons/project-icon.png" border="false"::: **Azure DevOps** to [browse all team projects and teams](../../navigation/work-across-projects.md). +If you need to switch your team project, select :::image type="icon" source="../../../media/icons/project-icon.png"::: **Azure DevOps** to [browse all team projects and teams](../../navigation/work-across-projects.md). #### [Azure DevOps CLI](#tab/azure-devops-cli) ::: moniker range="azure-devops" -You can view and open a wiki page defined for a project using the `az devops wiki show` command. To get started, see [Get started with Azure DevOps CLI](../../../cli/index.md). +You can view and open a wiki page for a project by using the `az devops wiki show` command: > [!div class="tabbedCodeSnippets"] ```azurecli @@ -26,29 +29,33 @@ az devops wiki show --wiki [--subscription] ``` -### Parameters +For more information, see [Get started with the Azure DevOps CLI](../../../cli/index.md). -- **--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`. +### Basic parameters -::: moniker-end +The following parameters are available for the `wiki show` command: -::: moniker range="azure-devops" +| Parameter | Required | Description | +|------------------|:--------:|-------------| +| `--wiki` | Yes | The name or ID of the wiki. | +| `--open` | No | Open the wiki page in your web browser. | +| `--project -p` | No | The name or ID of the project. | +| `--subscription` | No | The name or ID of the subscription. You can configure the default subscription with the `az account set -s NAME_OR_ID` command. | + +For more information, see the Azure DevOps CLI [command reference](/cli/azure/devops/wiki#az-devops-wiki-show). -### Example +### Example: View the project wiki -Open a wiki named 'myprojectwiki'. +The following example shows how to open a wiki named "MyProjectwiki": > [!div class="tabbedCodeSnippets"] ```azurecli -az devops wiki show --wiki myprojectwiki --open +az devops wiki show --wiki MyProjectwiki --open ``` ## View a wiki page -To get the content of a page via the Azure DevOps CLI, enter the `az devops wiki show` command. +You can view the content of a specific page by using the Azure DevOps CLI `az devops wiki show` command: > [!div class="tabbedCodeSnippets"] ```azurecli @@ -61,26 +68,29 @@ az devops wiki page show --path [--version] ``` -### Parameters +### More parameters -- **--path**: Required. Path of the wiki page. -- **--wiki**: Required. Name or ID of the wiki. -- **--include-content**: Optional. Include content of the page. -- **--open**: Optional. Open the wiki page in your web browser. -- **--project -p**: Optional. Name or ID of the project. -- **--version -v**: Optional. Version (ETag) of the wiki page. +The following table lists [more parameters](#basic-parameters) for the `wiki show` command when you want to view a specific page: -### Example +| Parameter | Required | Description | +|---------------------|:--------:|-------------| +| `--path` | Yes | The fully qualified path for the wiki page. | +| `--include-content` | No | Show the full page content along with the page metadata. | +| `--version -v` | No | The version of the wiki page, which corresponds to the `ETag` entity tag value. | -Get wiki page content with path 'my wiki' in a wiki named 'myprojectwiki'. +For more information, see the Azure DevOps CLI [command reference](/cli/azure/devops/wiki#az-devops-wiki-show). + +### Example: View a specific page + +The following example shows how to get content for the "Get Started" page of the "MyProjectwiki" wiki: > [!div class="tabbedCodeSnippets"] ```azurecli -az devops wiki page show --path 'my wiki' --wiki 'myprojectwiki' --content "Hello World" +az devops wiki page show --path 'Get Started' --wiki 'MyProjectwiki' --content "Hello World" ``` ::: 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..cd3e54caf0d 100644 --- a/docs/project/wiki/includes/wiki-naming-conventions.md +++ b/docs/project/wiki/includes/wiki-naming-conventions.md @@ -1,46 +1,38 @@ --- ms.topic: include +ms.date: 06/03/2025 --- -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. +Each wiki page corresponds to a file in the wiki Git repository. The following restrictions apply to page file names and the file size: -::: moniker range=">= azure-devops-2019" +- **File name**: When choosing a name for the page file, keep in mind that the fully qualified path to the file should be 235 characters or less. The full path to the page consists of the repo URL, the folder path to the page file, and the page file name. For example, `https://github.com/ExampleWiki/Contributors/Code/How-to-add-code-to-the-project.md`. +- **Uniqueness**: The page file name must be unique within its folder location in the wiki repo hierarchy. The name is case sensitive. +- **Special characters**: The page file name has restrictions about the following special characters: + - No Unicode control characters or surrogate characters + - No printable characters: forward slash `/`, back slash `\`, hash `#` + - No period `.` symbol at the start or end of the name -|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 `.`.| -| File size | Must not exceed the maximum of 18 MB. | -| Attachment file size | Must not exceed the maximum of 19 MB. | +- **File size**: The maximum page file size is 18 MB. +- **Attachment file size**: The maximum size for any attachment to a page file is 19 MB. -### Special characters in Wiki page titles +### Allowed special characters -You can specify page titles which contain one or more of these special characters `: < > * ? | -`. For example, you can name a Markdown file as "FAQ?" or "Set-up guide". The characters have the following URI encoded strings: +Several special characters are allowed in a page file name, such as the colon `:` and hyphen `-`. For example, you might name a Markdown file as _FAQ:0525_ or _Setup-Guide_. -> [!div class="mx-tdCol2BreakAll"] -> | Character | Encoded string | -> |------|---------| -> | `:` | %3A | -> | `<` | %3C | -> | `>` | %3E | -> | `*` | %2A | -> | `?` | %3F | -> | `|` | %7C | -> | `-` | %2D | -> | `"` | %22 | +> [!IMPORTANT] +> To avoid errors in page syntax and browser navigation, don't use the space character (` `) in page file names. If you name your page files based on the page title, replace any spaces in the page title with a hyphen (`-`) in the file name. -::: moniker-end +The following table lists the special characters allowed in wiki page file names and the corresponding URI encoded string: -::: moniker range="tfs-2018" +| Character | Symbol | URI string | +|------------|:-------:|:---------------:| +| **Colon** | `:` | %3A | +| **Left angle bracket** | `<` | %3C | +| **Right angle bracket** | `>` | %3E | +| **Asterisk** (_wildcard_) | `*` | %2A | +| **Question mark** | `?` | %3F | +| **Pipe** | `|` | %7C | +| **Hyphen** (_dash_) | `-` | %2D | +| **Double quote** | `"` | %22 | -> [!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 +For example, the file name _FAQ:0525_ is encoded as `FAQ%3A0525`. \ No newline at end of file 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..d7fe4be4ff0 --- /dev/null +++ b/docs/project/wiki/includes/wiki-prereqs-create-repository.md @@ -0,0 +1,10 @@ +--- +ms.topic: include +ms.date: 05/30/2025 +--- + +| 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 can view the wiki, including [Stakeholders](../../../organizations/security/get-started-stakeholder.md). | +| **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..0bc98f5e3c4 100644 --- a/docs/project/wiki/manage-readme-wiki-permissions.md +++ b/docs/project/wiki/manage-readme-wiki-permissions.md @@ -1,55 +1,88 @@ --- -title: Manage permissions for READMEs and wiki pages +title: Manage Permissions for READMEs and Wiki Pages titleSuffix: Azure DevOps -description: Learn how to set permissions to grant or secure access to README files and your team project built-in wiki. +description: Learn how to set permissions to grant or secure access to README files and your team project built-in wiki in Azure DevOps. ms.subservice: azure-devops-wiki ms.custom: wiki, devdivchpfy22 -ms.topic: conceptual -ms.assetid: +ms.topic: concept-article ms.author: chcomley author: chcomley ms.reviewer: gopinach -ms.date: 06/21/2022 -monikerRange: '>= tfs-2018' +ai-usage: ai-assisted +ms.date: 07/02/2025 +monikerRange: "<=azure-devops" +#customer intent: As an Azure DevOps developer, I want to manage permissions for README files and my team project wiki to ensure secure access for users. --- -# 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. +This article describes how to set and manage permissions for your team project wiki and project README files. By default, all members of the Contributors group have permission to edit wiki pages. - +## Manage permissions for wikis -## Manage wiki permissions +By default, all project Contributors have "read" and "edit" access to the Git repository for the project wiki. You can manage these permissions and 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//`) in Azure DevOps. -::: moniker range="tfs-2018" -> [!NOTE] -> **Feature availability**: The built-in wiki is available with TFS 2018 and later versions. -::: moniker-end +2. Select **Project settings**. -To open the Security dialog, choose **More actions** > **Wiki security**. +3. Under **Repos**, select **Repositories**. -> [!div class="mx-imgBorder"] -> ![Wiki, Choose More, select security](media/wiki/wiki-open-security.png) +4. Select the wiki repository, typically named `.wiki`. -For definitions of each repository permission, see [Git repository permissions](../../organizations/security/permissions.md#git-repository). +5. Select the **Security** tab to manage permissions for the wiki repository. -:::image type="content" source="media/wiki/security-dialog.png" alt-text="Wiki security dialog/"::: + The Security tab displays a list of users and groups with their current permissions. You can modify permissions for existing users/groups. -## Don't have access to create a page? + For definitions of each repository permission, see [Git repository (object-level) permissions](../../organizations/security/permissions.md#git-repository-object-level). -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. +> [!NOTE] +> If you don't have access to create a wiki page, you can request access from a project Administrator. They can grant you adequate permission on the underlying Git repository for the wiki. + +## Grant Edit permissions to an individual or group + +To grant *Edit* permissions to an individual or group, complete the following steps: + +1. Sign in to your project (`https://dev.azure.com//`) in Azure DevOps. + +2. Select **Project settings**. + +3. Under **Repos**, select **Repositories**. + +4. Select the wiki repository, typically named `.wiki`. + +5. Select the **Security** tab. + +6. In the security permissions list, find the user or group you want to modify, or select a group like **Contributors** to modify permissions for all members of that group. + +7. To add a new user, modify permissions for existing groups that the user is already a member of. + + > [!NOTE] + > The exact method for adding users and groups might vary. If there isn't an option to add users directly in the repository security settings, you might need to add users to existing project groups, like Contributors, through **Project settings** > **General** > **Teams** or **Project settings** > **Permissions**. + +8. To grant *Edit* permissions, locate the **Contribute** permission and set it to **Allow**. + +9. The changes save automatically. + +### Other considerations + +When you assign permissions to project users, review the following considerations: + +- Ensure 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 +Users with project Stakeholder access have permissions set for *private* and *public* 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 @@ -57,13 +90,12 @@ 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 +## Related content -- [Default Git repository and branch permissions](../../organizations/security/default-git-permissions.md) +- [Clone and update wiki content offline](wiki-update-offline.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..2e804f84d09 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 | @@ -33,7 +37,7 @@ Learn the following CLI commands for managing wikis. |[az devops wiki page create](#create-a-wiki-page) | Add a new page. | |[az devops wiki page delete](add-edit-wiki.md#delete-wiki-page) | Delete a page. | |[az devops wiki page show](add-edit-wiki.md#view-a-wiki-page) | Get the content of a page or open a page. | -|[az devops wiki page update](add-edit-wiki.md#edit-wiki-page) | Edit a page. | +|[az devops wiki page update](add-edit-wiki.md#edit-and-delete-wiki-pages) | Edit a page. | |[az devops wiki show](#show-wiki) | Show the details of a wiki. | ## Create a wiki @@ -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..046e5012b3d 100644 --- a/docs/project/wiki/markdown-guidance.md +++ b/docs/project/wiki/markdown-guidance.md @@ -1,685 +1,810 @@ --- -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: Use Markdown syntax to format content as tables, lists, headings, links, math notation, and more. 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.assetid: 43D2156E-2E20-42B8-B816-43E95CB479C5 +ai-usage: ai-assisted ms.author: chcomley author: chcomley ms.reviewer: gopinach -ms.topic: conceptual +ms.topic: concept-article monikerRange: '<= azure-devops' -ms.date: 02/17/2023 +ms.date: 06/18/2025 +#customer intent: As an Azure DevOps developer, I want to use Markdown to create tables, lists, headings, and more, so I can share my project information in pull requests, README files, dashboards, and wikis. --- -# 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/). +This article describes the basic syntax for using Markdown (_.md_) format with Azure DevOps features, including [Wiki pages](#markdown-in-an-azure-devops-wiki). Markdown syntax lets you add special formatting to your page content, such as headings, lists, tables, and images. Use Markdown to format your README files, dashboards, pull request content, and so on. -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. +You have two formatting options: common [Markdown conventions](https://daringfireball.net/projects/markdown/syntax) and [Markdown extensions for GitHub](https://docs.github.com/get-started/writing-on-github). -For more supported syntax for wiki pages, see [Wiki Markdown guidance](wiki-markdown-guidance.md). +## Support for Azure DevOps features -You can provide guidance in the following areas using Markdown: +Markdown syntax covers a wide range of formatting options, such as content headers, reference links, text emphasis like bold, and file attachments. Not all Markdown syntax is available for all features in Azure DevOps. Some of the significant features that support Markdown syntax include: -::: moniker range=">= azure-devops-2019" +- Criteria for the [Definition of Done (board)](../../boards/boards/add-columns.md#definition-of-done) for project milestones +- Information like team goals and metrics with the [Markdown widget](../../report/dashboards/add-markdown-to-dashboard.md) +- [Pull requests](../../repos/git/pull-requests.md) for project files in a Git repository +- [README files](../../repos/git/create-a-readme.md) in a Git repo to support contributors +- [Wiki files](add-edit-wiki.md) for page content in a team project wiki -- [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 +> [!NOTE] +> Markdown in Azure DevOps doesn't support JavaScript or iframes. For example, you can't embed interactive elements like countdown timers directly. + +The following table outlines the feature support for different Markdown elements and provides links to the syntax sections in this article. The table uses the notation Definition of **Done**, Markdown **Widget**, Pull requests (**PR**), **README** files, and **Wiki** files. + +| Markdown type | Done | Widget | PR | README | Wiki | +|-----------------------------------------|:----:|:------:|:---:|:------:|:----:| +| [Headers](#headers) | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | +| [Paragraphs and line breaks](#breaks) | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | +| [Block quotes](#block-quotes) | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | +| [Horizontal rules](#rules) | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | +| [Emphasis](#emphasis) | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | +| [Code highlighting](#code) | | | ✔️ | ✔️ | ✔️ | +| [Suggest change](#suggest-change) | | | ✔️ | | | +| [Tables](#tables) | | ✔️ | ✔️ | ✔️ | ✔️ | +| [Lists](#lists) | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | +| [Links](#links) | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | +| [Images](#images) | | ✔️ | ✔️ | ✔️ | ✔️ | +| [Checklist or task list](#checklists) | | | ✔️ | | ✔️ | +| [Emojis](#emoji-reactions) | | | ✔️ | | ✔️ | +| [Ignore or escape Markdown](#ignore) | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | +| [Attachments](#attachments) | | | ✔️ | | ✔️ | +| [Mathematical notation](#math-notation) | | | ✔️ | | ✔️ | -::: moniker range="tfs-2018" +## Headers -- [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) +Structure your content by using Markdown headers. Headers help to separate long portions of page content into sections that are easier to read. You can add headers in a [Definition of Done (board)](../../boards/boards/add-columns.md#definition-of-done), the [Markdown widget](../../report/dashboards/add-markdown-to-dashboard.md), pull requests, Readme files, and wiki files. -> [!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. +To define a top-level header, start a line with a single hash mark `#` followed by the heading text, such as `# Get Started on the Project`. Organize your remarks with subheaders by starting the line with more than one hash mark like `## Request Permissions` or `### Send Feedback`. You can use up to six hash marks to create size levels of headers. -::: moniker-end +### Example: Create headers in Markdown -> [!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. +The following Markdown creates a top-level header (H1) and four levels of subheaders (H2, H3, H4, and H5): -## Headers +```md +# This is a top-level (H1) header +## This is a subheader (H2) +### This is a lower subheader (H3) +#### This is an H4 header +##### This is an H5 header +``` -#### Supported in: Definition of Done | Markdown widget | Pull Requests | README files | Wikis +The following image shows the published view of the Markdown: -Structure your comments using headers. Headers segment longer comments, making them easier to read. +:::image type="content" source="media/markdown-guidance/markdown-headers.png" alt-text="Screenshot that shows a published view of the Markdown syntax for five levels of headers."::: -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. + -**Example:** -```markdown -# This is a H1 header -## This is a H2 header -### This is a H3 header -#### This is a H4 header -##### This is a H5 header -``` +## Paragraphs and line breaks -**Result:** +Make your text easier to read by breaking long portions into smaller paragraphs or insert line breaks to create spaces between lines of text. -:::image type="content" source="media/markdown-guidance/mrkdown-headers.png" alt-text="Screenshot of Web portal, headers 1 through 5."::: +You can add paragraphs and line breaks in a [Definition of Done (board)](../../boards/boards/add-columns.md#definition-of-done), the [Markdown widget](../../report/dashboards/add-markdown-to-dashboard.md), pull requests, Readme files, and wiki files. -## Paragraphs and line breaks +### Example: Add breaks in Markdown and pull requests -#### Supported in: Definition of Done | Markdown widget | Pull Requests | README files | Wikis +Comments in a pull request accept Markdown, such as **Bold** and _Italic_ style for text. You can also use the **Enter** key to insert a line break to start new text on the next line or add spacing between lines. -Make your text easier to read by breaking it into paragraphs or line breaks. +In the following Markdown, the author uses the **Enter** key to start the second sentence on a new line: -### Pull requests +```md +_Markdown_ lets you separate long lines of text by using the **Enter** key in a pull request comment. +Select **Enter** once to start text on a new line. +Select **Enter** twice to insert a blank line between lines of text. +``` -In pull request comments, select **Enter** to insert a line break and begin text on a new line. +The following image shows the published view of the Markdown for spacing in a pull request comment: -**Example - pull request comment:** +:::image type="content" source="media/markdown-guidance/markdown-breaks.png" alt-text="Screenshot that shows a published view of the Markdown syntax for line and paragraph breaks."::: -

      -Add lines between your text with the **Enter** key.
-Your text gets better spaced and makes it easier to read.
-
      +### Example: Add breaks in Markdown files or widgets -**Result:** +In a Markdown file or Markdown widget, you can separate lines of text to create new paragraphs. Add two spaces (**Space** key) before the line break, and select **Enter** to start a new paragraph. -Add lines between your text with the **Enter** key. +```md +Add two **Space** characters before the end of the line and then select **Enter**. +The next paragraph starts on a new line. The two paragraphs are separated by a blank line. +``` -Your text gets better spaced and makes it easier to read. +The following image shows the published view of the Markdown for spacing in a widget: -### Markdown files or widgets +:::image type="content" source="media/markdown-guidance/markdown-widget-breaks.png" alt-text="Screenshot that shows a published view of the Markdown syntax for the Enter and Space keys."::: -In a Markdown file or widget, enter two spaces before the line break, and then select **Enter** to begin a new paragraph. +## Block quotes -**Example - Markdown file or widget:** +Quote comments or text to set the context for your new comment or text. The quoted text displays indented from the left margin with a vertical line along the quoted section. -
      -Add two spaces before the end of the line, and then select **Enter**.(space, space, Enter)
-A space gets added in between paragraphs.
-
      +You can add block quotes in a [Definition of Done (board)](../../boards/boards/add-columns.md#definition-of-done), the [Markdown widget](../../report/dashboards/add-markdown-to-dashboard.md), pull requests, Readme files, and wiki files. -**Result:** +To quote a single line of text or a paragraph block, insert a right angle bracket `>` before the first text. -Add two spaces before the end of the line, and then select Enter. +To creat a nested quote, insert two or more brackets before the text. The nested quote is indented further from the left margin with double vertical lines along the quoted section. -A space gets added in between paragraphs. +### Example: Quote text by using brackets -## Blockquotes +```md +> Insert a bracket ">" before the text to quote the line of text. -#### Supported in: Definition of Done | Markdown widget | Pull Requests | README files | Wikis +This text references the quoted sentence. -Quote previous comments or text to set the context for your comment or text. +> To quote a paragraph, insert a bracket ">" before the first text. The other lines in the paragraph are also included in the block quote. Notice the entire paragraph is indented from the left margin and highlighted with a vertical line. -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. +This text references the quoted paragraph. -**Example:** +>> Insert two or more brackets ">>" before the text to create a nested quote. -
      -> Single line quote
->> Nested quote
->> multiple line
->> quote
-
      +>>> Nested quotes can also be multiple lines of text. Notice the nested quote text is indented further from the left margin and a vertical line is drawn for each level of bracket you insert. -**Result:** +This text references the nested block quotes. +``` -![Quoting in Markdown](media/markdown-guidance/markdown_quote2.jpg) +The following image shows the published view of the Markdown for quoted text: -## Horizontal rules +:::image type="content" source="media/markdown-guidance/markdown-block-quotes.png" alt-text="Screenshot that shows a published view of the Markdown syntax for quoting blocks of text."::: -#### 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. +## Horizontal rules -**Example:** +Underline or separate content and page sections with horizontal rules. You can add separators in a [Definition of Done (board)](../../boards/boards/add-columns.md#definition-of-done), the [Markdown widget](../../report/dashboards/add-markdown-to-dashboard.md), pull requests, Readme files, and wiki files. -
      -
      -above
- 
-----
-below
-
      -
      +To add a horizontal rule, enter a blank line and then another line with three hyphens (dashes) `---`. -**Result:** +### Example: Insert horizontal separators -above +The following Markdown creates two horizontal rules: ------ +```md +Text **above** a horizontal rule + +--- +Text **between** horizontal rules + +--- +Text **under** a horizontal rule +``` -below +The following image shows the published view of the Markdown for horizontal rules: -## Emphasis (bold, italics, strikethrough) +:::image type="content" source="media/markdown-guidance/markdown-horizontal-rules.png" alt-text="Screenshot that shows a published view of the Markdown syntax for horizontal rules."::: -#### Supported in: Definition of Done | Markdown widget | Pull Requests | README files | Wikis + -You can emphasize text by applying bold, italics, or strikethrough to characters: +## Emphasis (bold, italics, strikethrough) -- To apply italics: surround the text with an asterisk `*` or underscore `_` -- To apply bold: surround the text with double asterisks `**`. -- To apply strikethrough: surround the text with double tilde characters `~~`. +Markdown provides several style options for emphasizing text: -Combine these elements to apply emphasis to the text. +| Style | Example | Markdown | +|-------------------|----------------------|----------| +| **Italics** | _Italicized text_ | Enclose text within single asterisk `*` or underscore `_` characters. | +| **Bold** (Strong) | __Bolded text__ | Enclose text within double asterisk `**` or underscore `__` characters. | +| **Strikethrough** | ~~Crossed out text~~ | Enclose text within double tilde `~~` characters. | -::: moniker range=">= azure-devops-2019" +You can combine these styles to apply emphasis to the text. The emphasis styles are available in a [Definition of Done (board)](../../boards/boards/add-columns.md#definition-of-done), the [Markdown widget](../../report/dashboards/add-markdown-to-dashboard.md), pull requests, Readme files, and wiki files. > [!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. +> There's no Markdown syntax for underlining text. In a wiki page, you can underline text by using the HTML underline `` element. -::: moniker-end +### Example: Emphasize text -::: moniker range="tfs-2018" +The following Markdown shows how to emphasize text by using different styles and combining styles: -> [!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. +```md +**Italics** highlights text in a larger block like _new terminology_. -::: moniker-end +**Bold** (strong) adds presence to text, such as **Important!** -**Example:** +**Strikethrough** is useful for corrections like "Send feedback ~~to the team~~. -
      -Use _emphasis_ in comments to express **strong** opinions and point out ~~corrections~~  
-**_Bold, italicized text_**  
-**~~Bold, strike-through text~~**
-
      +Combine styles for other effects, such as ~~__Content removed__~~ and **_Milestones_**. +``` -
      +The following image shows the published view of the Markdown for text emphasis styles: -**Result:** +:::image type="content" source="media/markdown-guidance/markdown-emphasis-styles.png" alt-text="Screenshot that shows a published view of the Markdown syntax for text emphasis styles."::: -Use _emphasis_ in comments to express **strong** opinions and point out corrections -**_Bold, italicized text_** -**~~Bold, strike-through text~~** + ## Code highlighting +Highlight text blocks or inline text as code by using code highlights. You can add code highlighting in pull requests, Readme files, and wiki files. -#### Supported in: Pull Requests | README files | Wikis +To format a text block as code, enclose the block within three backtick (` ``` `) characters. The backticks that start and end the section must be on a separate line from the code block to highlight. -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 (`). +You can also format a portion of text within a larger text block as an inline code segment. For this style, enclose the inline code within single backticks. The backticks are inline with the text and not on separate lines. -> [!NOTE] -> Code highlighting entered within the Markdown widget renders code as plain preformatted text. +Code highlighting entered in the Markdown widget renders code as plain preformatted text. +### Example: Highlight code block in Markdown widget -**Example:** +The following example shows how to highlight a text block as code in the Markdown widget: -
      ```
-sudo npm install vsoagent-installer -g  
-```
-
      - -
      +```bash + +sudo npm install vsoagent-installer -g + +``` -**Result:** +The following example shows the published view of the Markdown for a text block highlighted as code: -``` +```bash sudo npm install vsoagent-installer -g ``` -
      - -**Example:** +### Example: Highlight inline code in Markdown widget -
      -To install the Microsoft Cross Platform Build & Release Agent, run the following: `$ sudo npm install vsoagent-installer -g`.
-
      +The following example shows how to highlight a portion of text as an inline code segment in the Markdown widget: -
      +```md +To install the Microsoft Cross Platform Build and Release Agent, run the following: $ sudo npm install vsoagent-installer -g +``` -**Result:** +The following image shows the published view of the Markdown for a portion of text highlighted as an inline code segment: -To install the Microsoft Cross Platform Build & Release Agent, run the following command: `$ sudo npm install vsoagent-installer -g`. +:::image type="content" source="media/markdown-guidance/markdown-widget-inline-code.png" alt-text="Screenshot that shows a published view of the Markdown syntax for a portion of text highlighted as an inline code segment."::: -
      +### Example: Convert text to code, identify code language -Within a Markdown file, text with four spaces at the beginning of the line automatically converts to a code block. +There's an alternate method for converting a text block into code. When a line of text in the Markdown starts with four spaces in the left margin, the text automatically converts to a code block. The following example demonstrates this behavior: -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. - -
      -``` language
-code
+```md
+    This article is a Markdown file (_.md_). This line of text automatically formats as code because the line starts with four spaces in the left margin.
 ```
-
      -
      +The preferred approach is to enclose the text within three backticks so you can specify the language identifier. The identifier applies syntax highlighting to the code according to the conventions of the specified language. Identifier labels are available for most programming languages, such as JavaScript (`js`), C# (`csharp`), and Markdown (`md`). For the list of supported languages, see the [highlightjs](https://github.com/highlightjs/highlight.js/tree/stable-11/src/languages) GitHub repository. + +The following examples show how to identify a text block as JavaScript or C#. You add the language identifier label after the first three backticks, as in ` ```md `. -**More examples:** +**JavaScript** -
      -``` js
+```Code Snippet
+
 const count = records.length;
-```
-
      + +``` -``` js +Here's the published view of the JavaScript code: + +```js const count = records.length; ``` -
      +**C#** -
      -``` csharp
+```Code Snippet
+
 Console.WriteLine("Hello, World!");
+
 ```
-
      -``` csharp +Here's the published view of the C# code: + +```csharp Console.WriteLine("Hello, World!"); ``` -## Tables +## Suggest change -#### Supported in: Markdown widget | Pull Requests | README files | Wikis +GitHub pull requests support the **Comment** feature where contributors can provide input and suggest changes. You can add a comment for a specific line or multiple lines in a file. The pull request author can apply the suggested change in a comment by selecting **Apply Change**. This action commits the change to the pull request and starts a build. -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. +If you add a comment that includes code highlighting in the Markdown widget, the code renders in a differences format. The changes in the modified line are annotated to show the differences. The minus symbol `-` indicates removed content and the plus symbol `+` highlights new content. -- 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 `\|`. -- 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. -- You must enter a blank space before and after work item or pull request (PR) mentioned inside a table cell. +### Example: Suggest changes in a pull request comment -**Example:** +The following example shows how to suggest code changes on a pull request in the Markdown widget. In this scenario, the code block uses the identifier `suggestion`: -```markdown -| Heading 1 | Heading 2 | Heading 3 | -|-----------|:-----------:|-----------:| -| Cell A1 | Cell A2 | Cell A3 | -| Cell B1 | Cell B2 | Cell B3
      second line of text | +``` + + for i in range(A, B+100, C): + ``` +The following image shows the differences view with the comment suggestion: -**Result:** +:::image type="content" source="media/markdown-guidance/suggestion-snapshot.png" alt-text="Screenshot that shows an example of a suggested change for code in a pull request comment."::: -| Heading 1 | Heading 2 | Heading 3 | -|-----------|:---------:|-----------:| -| Cell A1 | Cell A2 | Cell A3 | -| Cell B1 | Cell B2 | Cell B3
      second line of text | +For more information, see [Suggest changes in comments](../../repos/git/review-pull-requests.md?tabs=browser#suggest-changes-in-comments). -## Lists +## Tables -#### Supported in: Definition of Done | Markdown widget | Pull Requests | README files | Wikis +Organize structured data with Markdown tables. You can add tables in the Markdown widget, pull requests, Readme files, and wiki files. Tables are especially useful for describing function parameters, object methods, and other data with a clear name-to-description mapping. +Here are some points about working with tables in Markdown: -Organize related items with lists. You can add ordered lists with numbers or unordered lists with just bullets. +- Create each row on a separate line and end each row with a carriage return (CR) or line feed (LF). +- Create columns with hyphens `-` and the pipe symbol `|`, as in `|---|---|---|`. +- Define the column headers in the first row, as in `| First | Middle | Last |`. +- Define the column alignment (left, center, right) by using colons `:` in the second row, as in `|:--|:--:|--:|`. +- Escape the pipe symbol with a backslash `\|` when used in table text, as in `| Describe the pipe \| symbol. |` +- Add line breaks within a cell by using the HTML break tag `
      `. This approach works within a wiki but not elsewhere. +- Add a blank space before and after a work item or pull request mentioned in table text. -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. +### Example: Create a table -### Ordered or numbered lists +The following example shows how to create a table about with three columns and five rows in Markdown: -**Example:** -```markdown -1. First item. -1. Second item. -1. Third item. +```md +| Feature | Prerelease | Release target | +|:---|:---:|---:| +| Calculator | No | 10/27/2025 | +| Graphs | Yes | 8/18/2025 | +| Mail | No | 2/16/2025 | +| Tables | Yes | 10/27/2025 | +| Search | No | 1/5/2026 | ``` -**Result:** -1. First item. -2. Second item. -3. Third item. +Here's the published view of the Markdown table: -### Bulleted lists +| Feature | Prerelease | Release target | +|:---|:---:|---:| +| Calculator | No | 10/27/2025 | +| Graphs | Yes | 8/18/2025 | +| Mail | No | 2/16/2025 | +| Tables | Yes | 10/27/2025 | +| Search | No | 1/5/2026 | -**Example:** +## Lists -``` -- Item 1 -- Item 2 -- Item 3 -``` +Organize related items with different types of lists. Create an ordered list to show the precedence of items or items in a sequence. Create lists of related but unordered items by using bullet points. You can add list styles in a [Definition of Done (board)](../../boards/boards/add-columns.md#definition-of-done), the [Markdown widget](../../report/dashboards/add-markdown-to-dashboard.md), pull requests, Readme files, and wiki files. -**Result:** +Here are some points about working with lists in Markdown: -- Item 1 -- Item 2 -- Item 3 +- Specify each list item on a separate line. +- Start each item in an ordered list with a number followed by a period, as in `1. First item 2. Next item.` + You can also start each item with `1.` and let the publishing system determine the numbering for you. +- Start each item in an unordered list with a hyphen `-` or asterisk `*`, as in `- First point - Next point`. +- Check the spacing before and after lists in a Markdown file or widget: + - For the initial list, add a blank line before and after the list. + - For nested lists, use correct indentation. No extra before and after line breaks are needed. -### Nested lists +### Example: Create a numbered (ordered) list -**Example:** +The following example shows how to create a numbered list for items in a sequence by using Markdown: + +```md + +1. First step in the procedure. +1. Second step. +1. Third step. + ``` -1. First item. - - Item 1 - - Item 2 - - Item 3 -1. Second item. - - Nested item 1 - - Further nested item 1 - - Further nested item 2 - - Further nested item 3 - - Nested item 2 - - Nested item 3 + +Here's the published view of the Markdown ordered list: + +1. First step in the procedure. +1. Second step. +1. Third step. + +### Example: Create a bullet (unordered) list + +The following example shows how to create an unordered list of related items by using Markdown: + +```md + +- First item in the list. +- Next item. +- Last item. + ``` -**Result:** +Here's the published view of the Markdown unordered list: + +- First item in the list. +- Next item. +- Last item. + +### Example: Nested lists + +You can also create lists within lists and mix the styles. + +The following example shows how to create a numbered list that has nested bullet lists in Markdown: + +```md + +1. First step in the procedure. + - First item in a nested list. + - Next item. + - Last item. +1. Second step. + - First item in a nested list. + - First item in a subnested list. + - Next item. + - Last item. +1. Third step. + 1. First substep. + 1. Next substep. + 1. Last substep. + +``` -1. First item. - - Item 1 - - Item 2 - - Item 3 -2. Second item. - - Nested item 1 - - Further nested item 1 - - Further nested item 2 - - Further nested item 3 - - Nested item 2 - - Nested item 3 +Here's the published view of the list with nested lists: +1. First step in the procedure. + - First item in a nested list. + - Next item. + - Last item. +1. Second step. + - First item in a nested list. + - First item in a subnested list. + - Next item. + - Last item. +1. Third step. + 1. First substep. + 1. Next substep. + 1. Last substep. - + ## Links -#### Supported in: Definition of Done | Markdown widget | Pull Requests | README files | Wikis +Link to work items by entering the hash mark `#` followed by a work item ID, and then select the work item from the list. You can add different types of links in a [Definition of Done (board)](../../boards/boards/add-columns.md#definition-of-done), the [Markdown widget](../../report/dashboards/add-markdown-to-dashboard.md), pull requests, Readme files, and wiki files. -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. +Here are some points about working with links in Markdown: -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. +- The standard Markdown syntax for a link is `[Link display text](Link path)`. +- In pull request comments and wikis, URLs that start with HTTP or HTTPS automatically format as links. +- If you use the hash mark `#` in other ways like color hex codes, you can avoid auto suggestions for work items by prefixing the hash mark `#` with a backslash `\`. +- In Markdown files and widgets, you can create text hyperlinks for a URL by using the standard Markdown link syntax. The `Link path` can be relative or absolute. -In Markdown files and widgets, you can set text hyperlinks for your URL using the standard Markdown link syntax: + The following example shows how to specify a relative link in Markdown, where the text renders as a hyperlink: -```markdown -[Link Text](Link URL) -``` + ```md + For more information, see the [C# language reference](/dotnet/csharp/language-reference/). + ``` -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. + Here's the published view of the link: -**Supported links for Welcome pages:** + For more information, see the [C# language reference](/dotnet/csharp/language-reference/). -- Relative path: `[text to display](target.md)` -- Absolute path in Git: `[text to display](/folder/target.md)` -- Absolute path in TFVC: `[text to display]($/project/folder/target.md)` -- URL: `[text to display](http://address.com)` +### Supported links -**Supported links for Markdown widget:** +When you link to another Markdown page in the same Git or Team Foundation Version Control (TFVC) repository, you can specify the link target as a relative or absolute path. -
        -
      • URL: [text to display](http://address.com)
        • -
      +> [!NOTE] +> Links to documents on file shares (`file://...`) aren't supported for security purposes. -**Supported links for Wiki:** -
        -
      • Absolute path of Wiki pages: [text to display](/parent-page/child-page)
        • -
      • URL: [text to display](http://address.com)
        • -
      +The following sections provide examples for different Markdown scenarios. -> [!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). +#### Example: Welcome page relative links -**Example:** +Here are some examples of relative links in the Welcome page for a wiki: -``` -[C# language reference](/dotnet/csharp/language-reference/) -``` +- Relative path: `[Display text](target.md)` + +- Absolute path in Git: `[Display text](/folder/target.md)` + +- Absolute path in TFVC: `[Display text]($/project/folder/target.md)` + +- URL: `[Display text](http://address.com)` + +#### Example: Markdown widget relative links -**Result:** +The following example shows a relative link in a Markdown widget: -[C# language reference](/dotnet/csharp/language-reference/) +- URL: `[Display text](http://address.com)` - +#### Example: Wiki pages relative links + +Here are some examples of relative links in a wiki page: + +- Absolute path of Wiki pages: `[Display text](/parent-page/child-page)` + +- URL: `[Display text](http://address.com)` + + ### Source control relative links -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: +Relative links to source control files are interpreted differently in a Welcome page versus a Markdown widget: -- **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 +#### Example: Welcome page relative links -For example: +Relative links in a Welcome page are relative to the root of the source control depository where the Welcome page exists. Here are some examples: -| Welcome page | Markdown widget equivalent | -|--------------------|-----------------------------------| -| /BuildTemplates/AzureContinuousDeploy.11.xaml |/DefaultCollection/Fabrikam Fiber/_versionControl#path=$/Tfvc Welcome/BuildTemplates/AzureContinuousDeploy.11.xaml| -| ./page-2.md |/DefaultCollection/Fabrikam Fiber/_versionControl#path=$/Tfvc Welcome/page-2.md | +- _/BuildTemplates/AzureContinuousDeploy.11.xaml_ +- _./page-2.md_ -### Anchor links +#### Example: Markdown widget relative 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: +Relative links in a Markdown widget are relative to the team project collection URL base. Here are some examples: -- Punctuation marks and leading white spaces within a file name are ignored -- Upper case letters convert to lower case letter -- Spaces between letters convert to dashes (-) +- _/DefaultCollection/Fabrikam/versionControl#path=$/TFVC-Welcome/BuildTemplates/AzureContinuousDeploy.11.xaml_ +- _/DefaultCollection/Fabrikam/versionControl#path=$/TFVC-Welcome/page-2.md_ -**Example:** +### Anchor links -``` -###Link to a heading in the page -``` +When a Markdown file renders as HTML, the system assigns an anchor ID to each header on the page. The ID is a converted form of the header text. The system applies the following changes to create the ID: -
      +- Replace spaces in the header text with hyphens `-` +- Change uppercase letters to lowercase +- Ignore (don't include) most special characters, such as `#`, `@`, `$` +- Ignore (don't include) most punctuation, such as `:`, `"`, `?` +You use the hash mark `#` to link to the header in the document, as in `[Display text](#)`. -**Result:** +The following example shows a heading and a link its anchor ID: -The syntax for an anchor link to a section... +```md +#### Team #1 : Release Wiki! -
      -[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. +Welcome to the Release wiki. For more information, [Visit the Project Wiki](#team-1--release-wiki). +``` -You can also reference headings within another Markdown file: +Here's the published view: -
      -[text to display](./target.md#heading-id)  
-
      +#### Team #1 : Release Wiki! -
      -In wiki, you can also reference heading in another page: +Welcome to the Release wiki. For more information, [Visit the Project Wiki](#team-1--release-wiki). -
      -[text to display](/page-name#section-name)
-
      +You can also link to a heading in another Markdown file by specifying the file name with the anchor ID in the link: - +```md +[Set up a project wiki](about-readme-wiki.md#set-up-a-project-wiki). +``` -## Images +A wiki page is also a Markdown file. You can reference a heading in one page in the wiki from another page: -#### Supported in: Markdown widget | Pull Requests | README files | Wikis +```md +Welcome to the Wiki! -To highlight issues or make things more interesting, you can add images and animated GIFs to the following aspects of your pull requests: +- [Get Started](/get-started-page) +- [Contribute content](/get-started-page#contribute) +- [Send Feedback](/contact-page#send-feedback) +``` -- Comments -- Markdown files -- Wiki pages + -Use the following syntax to add an image: 
      ![Text](URL)
      The text in the brackets describes the linked image and the URL points to the image location. +## Images -**Example:** +Demonstrate concepts and add visual interest by using images and animated GIFs in your content. You can add images in the Markdown widget, pull requests, Readme files, and wiki files. -
      +The standard Markdown syntax for an image or animated GIF is `![Image alt text](Image path)`. The syntax is similar to the syntax for a link, but the line begins with an exclamation point `!` symbol.
 
-![Illustration to use for new users](https://azurecomcdn.azureedge.net/cvt-779fa2985e70b1ef1c34d319b505f7b4417add09948df4c5b81db2a9bad966e5/images/page/services/devops/hero-images/index-hero.jpg)
+The `Image alt text` value describes the image. The alt text value displays when the user hovers over the image in the published view. The `Image path` identifies the image location.
 
-
      +The following example adds an illustration to a Markdown file: -
      +```md +![Illustration to use for new users](https://azurecomcdn.azureedge.net/cvt-779fa2985e70b1ef1c34d319b505f7b4417add09948df4c5b81db2a9bad966e5/images/page/services/devops/hero-images/index-hero.jpg) +``` -**Result:** +### Image path The path to the image file can be a relative path or the absolute path in Git or TFVC, just like the path to another Markdown file in a link. - Relative path: `![Image alt text](./image.png)` - Absolute path in Git: `![Image alt text](/media/markdown-guidance/image.png)` -- Absolute path in TFVC: `![Image alt text]($/project/folder/media/markdown-guidance/image.png)` -- Resize image: `IMAGE_URL =WIDTHxHEIGHT` - > [!NOTE] - > Be sure to include a space before the equal sign. - >- Example: `![Image alt text]($/project/folder/media/markdown-guidance/image.png =500x250)` - >- It's also possible to specify only the WIDTH by leaving out the HEIGHT value: `IMAGE_URL =WIDTHx` +- Absolute path in TFVC: `![Image alt text]($/project/folder/media/markdown-guidance/image.png)` + +### Image size + +You can set the image size with the `Image-path =Image-widthxImage-height` syntax: + +- The letter `x` represents the `by` portion in the calculation expression "width-by-height." +- Don't add a space before or after the letter `x`. +- Do include a space before the equal `=` sign. +- If you prefer, you can specify the `Image-width` only, as in `Image-path =Image-widthx`. Notice that you still specify the letter `x`. + +The following example shows the Markdown syntax for an image where you specify a width of 500 and a height of 250: + +```md +![Image alt text](./image.png =500x250) +``` + + ## Checklist or task list -#### Supported in: Pull Requests | Wikis +Track the progress of your assignments and action items with lightweight task lists. You can add checklists or task lists in pull requests and wiki files. This feature is useful in the pull request description to track input from reviewers or in a wiki project page to track task status. -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. +### Example: Create checklist in Markdown -You can Use `[ ]` or `[x]` to support checklists. Precede the checklist with either `-` or `1.` (any numeral). +You can create a checklist directly in the Markdown: -**Example - Apply the task list Markdown to a highlighted list** +- Use empty square brackets `[]` to create a new task. +- Show a task as completed by including the letter `x` inside the square brackets `[x]`. +- Precede each task with a hyphen and space `-[]` or a number and space `1.[]`. You can use any numeral. +- Don't use a checklist inside a Markdown table. -> [!div class="mx-imgBorder"] -> ![Apply Markdown task list format to a highlighted list in a PR](media/markdown-guidance/checklist-pr-apply.png) +The following example creates a checklist with four items, where the first item is marked as completed: -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. +```md +- [x] Project plan +- [ ] Draft 1 code +- [ ] Draft 2 code +- [ ] Test plan +``` -> [!div class="mx-imgBorder"] -> ![Check the boxes to mark items as completed.](media/markdown-guidance/checklist-pr-applied-check.png) +Here's the published view of the checklist: -**Example - Format a list as a task list** +:::image type="content" source="media/markdown-guidance/markdown-checklists.png" alt-text="Screenshot that shows a checklist where the first item is marked as completed."::: -
      -- [ ] A  
-- [ ] B  
-- [ ] C  
-- [x] A  
-- [x] B  
-- [x] C  
+After the checklist is published, users can mark an item as completed by selecting the item checkbox in the list. 
 
-
      +### Example: Apply task list Markdown to selected text -
      +You can also select existing text in the web portal and use actions on the Markdown toolbar to apply the checklist format. After you add a checklist or task in this manner, you can edit the list or task in the Markdown. -**Result:** +The following image shows how to apply the **Task List** style on the Markdown toolbar to the selected text: -Checklists +:::image type="content" source="media/markdown-guidance/checklist-pr-apply.png" alt-text="Screenshot that shows how to apply the Task List style on the Markdown toolbar to selected text in a pull request."::: -> [!NOTE] -> A checklist within a table cell isn't supported. +A task is marked as completed by checking the task box in the list: -## Emoji +:::image type="content" source="media/markdown-guidance/checklist-pr-applied-check.png" alt-text="Screenshot that shows tasks marked as completed in the task list."::: -#### Supported in: Pull Requests | Wikis +## Emoji reactions -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/). +Add emoji reactions in pull requests and wiki files. You can use emoji reactions to add character and react to comments in the request. -**Example:** +Enter the name of an emotion or expression like `smile` and enclose the text within colon `:` characters. In the published view of the Markdown, your input is converted to the corresponding [emoji graphic](https://www.webpagefx.com/tools/emoji-cheat-sheet/). Markdown in Azure DevOps supports most emoji graphics. -
      -:smile:
-:angry:
-
      +### Example: Add emoji reactions in a pull request -
      +The following example shows how to add emoji reactions with Markdown in a pull request comment: -**Result:** +```md +The code review received :+1::+1: and the team is :smile: +``` -![Emojis in Markdown](../../repos/git/media/pull-requests/emoji-markdown.png) +Here's the published view of the emoji reactions: -To escape emojis, enclose them using the \` character. +:::image type="content" source="media/markdown-guidance/markdown-emoji-pull-request.png" alt-text="Screenshot that shows the published view of emojis in a pull request comment."::: -**Example:** +### Example: Escape emoji syntax in Markdown -
      `:smile:` `:)` `:angry:`
      +The following example shows how to escape emoji syntax with the backslash `\` character in Markdown: -**Result:** +```md +Markdown syntax for some emoji reactions: +- **Happy** \:smile: +- **Angry** \:angry: +- **Sad** \:cry: +``` - `:smile:` `:)` `:angry:` +Here's the published view of the Markdown that shows the emoji syntax: -## Ignore or escape Markdown syntax to enter specific or literal characters +:::image type="content" source="media/markdown-guidance/markdown-escape-emoji.png" alt-text="Screenshot that shows how to escape emoji syntax in Markdown by using the backslash '\' character."::: -#### Supported in: Definition of Done | Markdown widget | Pull Requests | README files | Wikis +In a pull request comment, you need two backslashes `\\` to escape the emoji syntax conversion. -:::row::: - :::column span="1"::: - **Syntax** - :::column-end::: - :::column span="1"::: - **Example/notes** - :::column-end::: -:::row-end::: -:::row::: - :::column span="1"::: - To insert one of the following characters, prefix with a \(backslash). - `\`, backslash - ```, backtick - `_`, underscore - `{}`, curly braces - `[]`, square brackets - `()`, parentheses - `#`, hash mark - `+`, plus sign - `-`, minus sign (hyphen) - `.`, period - `!`, exclamation mark - `*`, asterisk - :::column-end::: - :::column span="1"::: - Some examples on inserting special characters: - Enter `\\` to get \ - Enter `\_` to get _ - Enter `\#` to get # - Enter `\(` to get ( - Enter `\.` to get . - Enter `\!` to get ! - Enter `\*` to get * - :::column-end::: -:::row-end::: + + +## Special characters as literal text + +Publish special characters as literal text by using the backslash `\` as an escape character in the Markdown. The backslash causes the publishing system to bypass any interpretation and conversion process for the special character. The special character is shown as literal text in the published view. + +You can use ignore and escape syntax in a [Definition of Done (board)](../../boards/boards/add-columns.md#definition-of-done), the [Markdown widget](../../report/dashboards/add-markdown-to-dashboard.md), pull requests, Readme files, and wiki files. + +### Example: Publish special characters + +The Markdown syntax \`Enclose text in backticks\` has the published view `Enclose text in backticks`. The publishing system applies the `inline code` format to the text within the backticks (\`) and it doesn't publish the backticks. + +If you prefix the backtick (\`) with a backslash (\\), the format of the text within the backticks doesn't change and the backticks are published. This behavior is available for most special characters, including parentheses `()`, square brackets `[]]`, underscore `_`, hyphen `-`, hash mark `#` asterisk `*`, ``` backtick \` ```, and the backslash `\` itself. + +The following Markdown uses the backslash `\` character to publish special characters as literal text: + +```md +\\\ Code comment + +Show the **\_\_**underscores**\_\_** + +\# Code comment and not a **Heading** + +**\(** Include the **parentheses \)** + +Show the __\*__asterisks__\*__ and don't change to *italics* +``` + +Here's the published view of the Markdown: + +\\\ Code comment + +Show the **\_\_**underscores**\_\_** + +\# Code comment and not a **Heading** + +**\(** Include the **parentheses \)** + +Show the __\*__asterisks__\*__ and don't change to *italics* + +> [!NOTE] +> For some Markdown, you can enter the HTML code `\` for the backslash rather than the character symbol `\`. ## Attachments -#### Supported in: Pull Requests | Wikis +Attach files in pull request comments and wiki pages. Attachments can help illustrate your point or provide details about your suggestions. Attachments support the following file formats: -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. +:::row::: +:::column span="1"::: +**Attachment type** +:::column-end::: +:::column span="2"::: +**File formats** +:::column-end::: +:::row-end::: -Web portal, Pull Request, Attach files via drag and drop i +:::row::: +:::column span="1"::: +**Code** +:::column-end::: +:::column span="2"::: +C# (_.cs_), Extensible Markup Language (_.xml_), JavaScript Object Notation (_.json_), Hypertext Markup Language (_.html_, _.htm_), Layer (_.lyr_), Windows PowerShell script (_.ps1_), Roshal Archive (_.rar_), Remote Desktop Connection (_.rdp_), Structured Query Language (_.sql_) + +**Note**: Code attachments aren't supported in pull request comments. +:::column-end::: +:::row-end::: +:::row::: +:::column span="1"::: +**Compressed files** +:::column-end::: +:::column span="2"::: +ZIP (_.zip_), GZIP (_.gz_) +:::column-end::: +:::row-end::: +:::row::: +:::column span="1"::: +**Documents** +:::column-end::: +:::column span="2"::: +Markdown (_.md_), Microsoft Office Message (_.msg_), Microsoft Project (_.mpp_), Word (_.doc_, _.docx_), Excel (_.xls_, _.xlsx_, _.csv_), PowerPoint (_.ppt_, _.pptx_), Plain text (_.txt_), Portable Document Format (_.pdf_) +:::column-end::: +:::row-end::: +:::row::: +:::column span="1"::: +**Images** +:::column-end::: +:::column span="2"::: +PNG (_.png_), GIF (_.gif_), JPEG (_.jpeg_, _.jpg_), Icons (_.ico_) +:::column-end::: +:::row-end::: +:::row::: +:::column span="1"::: +**Visio** +:::column-end::: +:::column span="2"::: +VSD (_.vsd_, _.vsdx_) +:::column-end::: +:::row-end::: +:::row::: +:::column span="1"::: +**Video** +:::column-end::: +:::column span="2"::: +MOV (_.mov_), MP4 (_.mp4_) +:::column-end::: +:::row-end::: -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. +> [!NOTE] +> Not all file formats are supported as attachments in pull request comments, such as Microsoft Office Message (_.msg_) files. -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. -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. +### Attach images or files -Attachments support the following file formats: +There are several ways you can attach an image or file in a pull request **Comment** box or on a wiki page in the **Edit** pane: -> [!div class="mx-tdCol2BreakAll"] -> | Type | File formats | -> |------|---------| -> | Code | CS (.cs), Extensible Markup Language (.xml), JavaScript Object Notation (.json), Hypertext Markup Language(.html, .htm), Layer (.lyr), Windows PowerShell script (.ps1), Roshal Archive (.rar), Remote Desktop Connection (.rdp), Structured Query Language (.sql) - **Note: Code attachments aren't permitted in PR comments** | -> | Compressed files | ZIP (.zip) and GZIP (.gz) | -> | Documents | Markdown (.md), Microsoft Office Message (.msg), Microsoft Project (.mpp), Word (.doc and .docx), Excel (.xls, .xlsx and .csv), and Powerpoint (.ppt and .pptx), text files (.txt), and PDFs (.pdf) | -> | Images | PNG (.png), GIF (.gif), JPEG (both .jpeg and .jpg), Icons (.ico) | -> | Visio | VSD (.vsd and .vsdx) | -> | Video | MOV (.mov), MP4 (.mp4) | +- Drag and drop a file into the comment or onto the wiki page. +- Paste an image on your clipboard into the comment or onto the wiki page. The image renders directly in the comment or on the wiki page. +- Select the **Attach** (paperclip) icon in the comment or in the **Format** pane in your wiki page and choose the file to attach: -> [!NOTE] -> Not all file formats are supported within pull requests, such as Microsoft Office Message (.msg) files. + :::image type="content" source="media/markdown-guidance/attach-files.png" alt-text="Screenshot that shows how to select the paperclip icon to attach a file onto a wiki page."::: - - +When you attach a nonimage file, the system creates a link to the file in the comment or on the wiki page. You can change the link display text within the square brackets, as in `[Updated link display text](LINK URL)`. When you publish the page or comment, the user can select the link to access the attachment. -## Mathematical notation and characters + -#### Supported in: Pull Requests | Wikis +## Mathematical notation and characters -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: +You can use mathematical notation and characters in pull request comments and wiki files. Both inline and block [KaTeX](https://khan.github.io/KaTeX/function-support.html) notation are supported, which includes the following elements: - Symbols - Greek letters @@ -688,31 +813,27 @@ We support both inline and block [KaTeX](https://khan.github.io/KaTeX/function-s - Fractions and binomials - Other KaTeX supported elements -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. +In a Markdown file, mathematical notation is enclosed within dollar `$` signs. To create an expression inline with other text, enclose the notation with single dollar signs, `$ A + B = C $`. For a block expression, begin and end the block with two dollar signs, `$$ A = 1 \ B = 2 \ C = A + B $$`. -::: moniker-end +### Example: List Greek characters -### Example: Greek characters +The following example lists Greek characters used in mathematical notation by adding a code snippet in the Markdown file. Notice that the language identifier for the snippet is `KaTeX` and not Markdown `md`: ```KaTeX $ \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$ ``` -**Result:** -> [!div class="mx-imgBorder"] -> ![Greek letters](media/markdown-guidance/mathematical-notation-greek-characters.png) +Here's the published view of the Greek characters: + +:::image type="content" source="media/markdown-guidance/mathematical-notation-greek-characters.png" alt-text="Screenshot that shows the published view of the KaTex code snippet that lists Greek characters used in mathematical notation."::: -### Example: Algebraic notation +### Example: Use Algebraic notation + +The following example uses an inline notation and an algebraic block expression: ```KaTeX Area of a circle is $\pi r^2$ @@ -724,32 +845,488 @@ A_{triangle}=\frac{1}{2}({b}\cdot{h}) $$ ``` -**Result:** -> [!div class="mx-imgBorder"] -> ![Algebraic notation](media/markdown-guidance/mathematical-notation-algebra.png) +Here's the published view of the notation in the Markdown file: + +:::image type="content" source="media/markdown-guidance/mathematical-notation-algebra.png" alt-text="Screenshot that shows the published view of the KaTex code snippet that includes inline notation and an algebraic block expression."::: -### Example: Sums and Integrals +### Example: Show sums and integrals + +The following example uses two block expressions to calculate sums and integrals: ```KaTeX $$ \sum_{i=1}^{10} t_i $$ - $$ \int_0^\infty \mathrm{e}^{-x}\,\mathrm{d}x $$ ``` -**Result:** -> [!div class="mx-imgBorder"] -> ![Sums and Integrals.](media/markdown-guidance/mathematical-notation-sums-integrals.png) +Here's the published view of the expressions in the Markdown file: + +:::image type="content" source="media/markdown-guidance/mathematical-notation-sums-integrals.png" alt-text="Screenshot that shows the published view of the KaTex code snippet that uses two block expressions to calculate sums and integrals."::: + +## Markdown in an Azure DevOps wiki + +There are many ways you can use Markdown to enhance your Azure DevOps wiki. The following sections provide syntax examples for various tasks: + +- Add Mermaid diagrams like sequences, flowcharts, and user journeys +- Create a table of contents (TOC) for pages and subpages +- Configure collapsible page sections +- Embed videos and Azure Boards query results +- Link to work items with the hash mark `#` +- Use `@` mentions for users and groups +- Include HTML elements like `` for rich text +- Check the page visit count + +The availability of these features depends on your version of Azure DevOps. + +::: moniker range=">= azure-devops-2022" + +### Work with Mermaid diagrams + +Mermaid lets you create diagrams and visualizations by using text and code. The Azure DevOps 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). + +#### Limitations + +When you work with Mermaid diagram in Azure DevOps, keep in mind the following limitations: + +- Azure DevOps provides **limited syntax support** for the Mermaid diagram types. Unsupported syntax includes most HTML tags, Font Awesome, `flowchart` syntax (use `graph` element instead), LongArrow `---->`, and more. + +- Internet Explorer doesn't support Mermaid. If you use Mermaid diagrams in your wiki, the diagrams don't render in Internet Explorer. + +#### Example: Add Mermaid diagram to wiki page + +To add a Mermaid diagram to a wiki page, start and end the notation with three colons `:`. Specify the `mermaid` keyword, the diagram type, such as `sequenceDiagram`, and provide the information to illustrate. The information to diagram is specified as an indented section in the syntax. + +The following example shows how to add a Mermaid diagram to a wiki page: + +```md +::: mermaid + + +::: +``` + +#### Example: Sequence diagram + +A sequence diagram (type `sequenceDiagram`) is an interaction illustration that shows how processes operate with one another and in which order. + +The following example shows how to add a sequence diagram to a wiki page: + +```md +::: mermaid +sequenceDiagram + Christie->>Josh: Hello Josh, how are you? + Josh-->>Christie: Great! + Christie->>Josh: See you later! +::: +``` + +Here's the published view of the sequence diagram: + +:::image type="content" source="media/wiki/wiki-mermaid-sequence-diagram.png" alt-text="Screenshot of the Mermaid Live Editor with the code for a sequence diagram and a preview of the published view." lightbox="media/wiki/wiki-mermaid-sequence-diagram.png"::: + +#### Example: Gantt chart + +A Gantt chart (type `gantt`) records each scheduled task as one continuous bar that extends from left to right. The `x` axis represents time. The `y` axis records the tasks and their order for completion. + +When you exclude a date, day, or collection of dates specific to a task, the Gantt chart accommodates the changes. The chart extends by an equal number of days toward the right rather than creating a gap inside the task. + +The following example shows how to add a Gantt chart to a wiki page: + +```md +::: 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 +::: +``` + +Here's the published view of the Gantt chart: + +:::image type="content" source="media/wiki/wiki-mermaid-gantt-chart.png" alt-text="Screenshot of the Mermaid Live Editor with the code for a Gantt chart and a preview of the published view." lightbox="media/wiki/wiki-mermaid-gantt-chart.png"::: + +#### Example: Flowchart + +A flowchart (type `graph`) is composed of nodes, geometric shapes and edges, and arrows or lines. After you identify the `graph` diagram type, specify the flow direction for information in the chart, such as `TB;` for top-to-bottom. + +The following example creates a flowchart with the `graph` type. The graph information follows a left-to-right `LR;` direction. + +> [!NOTE] +> Azure DevOps doesn't support the `flowchart` diagram type, the arrow `---->` syntax, or links to and from a `subgraph` diagram type. + +```md +:::mermaid +graph LR; + A[Hard edge] -->|Link text| B(Round edge) --> C{Decision} + C -->|One| D[Result one] + C -->|Two| E[Result two] +::: +``` + +Here's the published view of the flowchart graph: + +:::image type="content" source="media/wiki/wiki-mermaid-flowchart.png" alt-text="Screenshot of the Mermaid Live Editor with the code for a flowchart graph and a preview of the published view." lightbox="media/wiki/wiki-mermaid-flowchart.png"::: + +#### Example: Class diagram + +The class diagram (type `classDiagram`) is the essential part of the object-oriented programming model. The diagram describes objects with their attributes and methods, and the inheritance between objects. + +The following example shows how to add a class diagram to a wiki page: + +```md +:::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() + } +::: +``` + +Here's the published view of the class diagram: + +:::image type="content" source="media/wiki/wiki-mermaid-class-diagram.png" alt-text="Screenshot of the Mermaid Live Editor with the code for a class diagram and a preview of the published view." lightbox="media/wiki/wiki-mermaid-class-diagram.png"::: + +#### Example: State diagram + +The state diagram (type `stateDiagram`) describes how system states can change when they transition from one state to another. + +The following example shows how to add a state diagram to a wiki page. This example uses version 2 of the state diagram type (type `stateDiagram-v2`). + +```md +:::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 + } +::: +``` + +Here's the published view of the state diagram: + +:::image type="content" source="media/wiki/wiki-mermaid-state-diagram.png" alt-text="Screenshot of the Mermaid Live Editor with the code for a state diagram and a preview of the published view." lightbox="media/wiki/wiki-mermaid-state-diagram.png"::: + +#### Example: User journey diagram + +The user journey (type `journey`) diagram describes what steps are required to complete a specific higher level action or task. + +The following example shows how to add a user journey diagram to a wiki page: + +```md +:::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 +::: +``` + +Here's the published view of the user journey diagram: + +:::image type="content" source="media/wiki/wiki-mermaid-user-journey.png" alt-text="Screenshot that shows a published preview of a user journey diagram in the Mermaid Live Editor." lightbox="media/wiki/wiki-mermaid-user-journey.png"::: + +#### Example: Pie chart + +The pie chart (type `pie`) diagram helps to visualize the percentages of information in a circle graph. After you identify the `pie` diagram type, specify the `title` keyword with a title for the pie chart. + +The following example creates a pie chart with the title `Fishermen in countries`: + +```md +:::mermaid +pie title Fishermen in countries + "Norway" : 684 + "Sweeden" : 234 + "Switzerland" : 10 +::: +``` + +Here's the published view of the pie chart: + +:::image type="content" source="media/wiki/wiki-mermaid-pie-chart.png" alt-text="Screenshot of the Mermaid Live Editor with the code for a pie chart and a preview of the published view." lightbox="media/wiki/wiki-mermaid-pie-chart.png"::: + +#### Example: Requirements diagram + +The requirements diagram (type `requirementDiagram`) creates a visualization of the requirements and their connections. + +The following example shows how to add a requirements diagram to a wiki page: + +```md +:::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 +::: +``` + +Here's the published view of the requirements diagram: + +:::image type="content" source="media/wiki/wiki-mermaid-requirements-diagram.png" alt-text="Screenshot of the Mermaid Live Editor with the code for a requirements diagram and a preview of the published view." lightbox="media/wiki/wiki-mermaid-requirements-diagram.png"::: + +::: moniker-end + +::: moniker range="<=azure-devops" + + + +## Table of contents for a wiki page + +Create a table of contents (TOC) for your wiki page by using the `[[_TOC_]]` syntax tag. When the publishing system encounters the tag and confirms at least one heading on the wiki page, it generates the TOC for the page. The title of the TOC on the page is "Contents." + +:::image type="content" source="media/toc-sample.png" alt-text="Screenshot that shows how to apply the TOC syntax tag to generate a TOC for a wiki page."::: + +To create the TOC, you can add the `[[_TOC_]]` syntax tag to the wiki page in the Markdown or select **More options** (**...**) > **Table of Contents** in the **Edit** view for the page. + +Here are some points about adding a TOC: + +- The syntax for the `[[_TOC_]]` tag is case-sensitive. If you specify the syntax by using lowercase `[[_toc_]]`, the TOC might not render. +- The publishing system renders the TOC for the first instance of the `[[_TOC_]]` tag in the Markdown page. It ignores other instances of the tag on the same page. +- You can place the `[[_TOC_]]` tag anywhere in the Markdown. The system renders the TOC on the page at the location where you placed the tag in the Markdown. +- The system confirms only Markdown style headings identified by the hash mark `#` syntax. It ignores HTML style heading tags. +- The system uses only the heading text to create the TOC entry. It ignores all extra HTML and Markdown syntax. + +The following example shows how the publishing system ignores extra formatting for a heading when it creates the entry for the TOC. The heading formats the word "Flagship" with _italics_, but the TOC entry for the heading removes the extra style. + +:::image type="content" source="media/toc-tags.png" alt-text="Screenshot that shows how the publishing system ignores extra formatting for a heading when it creates the entry for the TOC."::: + +::: moniker-end + +::: moniker range="azure-devops" + +## Table of subpages for a wiki page + +Add a table of subpages for a wiki page by using the `[[_TOSP_]]` syntax tag. The title of the table on the page is "Child Pages." The table includes an entry for each subpage of the wiki page. + +To create the table of subpages, you can add the `[[_TOSP_]]` syntax tag to the wiki page in the Markdown or select **More options** (**...**) > **Table of Subpages** in the **Edit** view for the page. + +Here are some points about adding a table of subpages: + +- The syntax for the `[[_TOSP_]]` tag is case-sensitive. If you specify the syntax by using lowercase `[[_tosp_]]`, the table of subpages might not render. +- The publishing system renders the table of subpages for the first instance of the `[[_TOSP_]]` tag in the Markdown page. It ignores other instances of the tag on the same page. +- You can place the `[[_TOSP_]]` tag anywhere in the Markdown. The system renders the table of subpages on the page at the location where you placed the tag in the Markdown. + +:::image type="content" source="media/wiki/wiki-table-content-subpages.png" alt-text="Screenshot that shows how the publishing system generates a table of subpages for a wiki page."::: + +::: moniker-end + +::: moniker range="<=azure-devops" + +## Collapsible sections in a wiki page + +Add a collapsible section in a wiki page with the HTML `
      ` syntax. You can use a collapsible section to limit visibility of specific content on the page, such as outdated or archived data, or set up a question/answer scenario. + +When the wiki page opens, the collapsible section is closed (collapsed), but the section summary is visible. Users can select the title to expand (open) and collapse the section as needed. + +Here are some points about adding a collapsible section: + +- Provide the title for the section within the `Title` tags. The summary is always visible on the page. +- Add a blank line after the closing `` tag. If you don't add the empty line, the section doesn't render correctly. +- Provide the main content after the blank line. You can use Markdown syntax and HTML to format the main content. +- If you create multiple collapsible sections on the page, add a blank line after each closing `
      ` tag. + +The following example creates a collapsible section on a wiki page: + +```html +# A collapsible section with Markdown syntax +
      + 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 of the Mermaid Live Editor with the code for a collapsible section and a preview of the published view."::: + +## Embedded videos + +Embed videos from YouTube and Microsoft Streams in a wiki page by using the `::: video :::` syntax. Inside the `video` declaration, define an ` +::: +``` + +Here's the published view of the wiki page with the video embedded: + +:::image type="content" source="media/wiki/wiki-embedded-video.png" alt-text="Screenshot that shows the published view of the wiki page with the embedded video."::: + + + +## Embedded Azure Boards query results + +Embed Azure Boards query results in a wiki page as a table by using the `query-table` syntax with a query ID: + +```md +Results from the Azure Boards query: + +::: +query-table 6ff7777e-8ca5-4f04-a7f6-9e63737dddf7 +::: +``` + +You can also select **More options** (**...**) > **Query Results** on the toolbar: + +:::image type="content" source="media/select-query-results.png" alt-text="Screenshot that shows how to select Query Results in the More options menu to embed the query results as a table in the wiki page."::: + +In the **Query Results** dialog, select the query results, and then select **Insert** to embed the results as table in the wiki page. + +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). + +## Notifications with @ mentions + +Create mentions for users or groups with the _at_ symbol `@`, as in `@`. When you enter the _at_ `@` symbol, the **Autosuggest** dialog opens where you can select users or groups to receive email notifications: + +:::image type="content" source="media/mention-autosuggest.png" border="false" alt-text="Screenshot that shows how to select a user in the Autosuggest dialog to add an @ mention in the wiki page."::: + +You can also select **More options** (**...**) > **@ Mention** on the toolbar: + +:::image type="content" source="media/select-at-mention.png" alt-text="Screenshot that shows how to select @ Mention in the More options menu to add a mention for a user or group in the wiki page."::: + +When you edit pages directly in code, use the following pattern, `@<{identity-guid}>`. + +::: moniker-end + +::: moniker range=">= azure-devops-2020" + +## Page visit count for a wiki page + +Add an automatically aggregated count of page visits for the last 30 days on every page in the wiki. A page visit is a view of the page by a specified user during a 15-minute interval. + +Use the batch API `pagesBatch` to see the daily count of visits to all pages in a paginated view. The view isn't sorted by number of visits. + +For data over 30 days old, use the REST API to get a list of all page visits. Sort the pages based on the number of visits and determine the top 100. You can store the visits in a dashboard or database. + +The following image shows the page count on a published wiki page: + +:::image type="content" source="media/wiki/wiki-page-visits.png" alt-text="Screenshot that shows the aggregated count of page visits on a published wiki page."::: + +::: moniker-end + + + +## HTML tags in wiki pages + +Create rich content by using HTML tags in wiki pages, such as `` and ``. In Azure DevOps Server 2019.1 and later, you can also paste rich content like images and video as HTML. + +### Example: Use Markdown syntax inside HTML + +The following example shows how to use Markdown syntax inside an HTML element in a wiki page. Add a blank line after the opening HTML element and before the Markdown: + +```html +

      + +This article describes how to **get started** with an Azure DevOps wiki. + +For more information, see the [Wikis, search, & navigation documentation](https://learn.microsoft.com/azure/devops/project/) for Azure DevOps. +

      +``` + +### Example: Embed a video with HTML + +The following example shows how to embed a video in a wiki page by using the `