@ppdostudio/ppdo-cli 0.0.0-stage → 1.0.0-beta.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +66 -0
- package/LICENSE +114 -0
- package/README.md +362 -3
- package/THIRD-PARTY-NOTICES +25 -0
- package/dist/bin.js +5 -0
- package/dist/chunks/ado-XAHQWYNQ.js +103 -0
- package/dist/chunks/api-7RAWLIQV.js +2 -0
- package/dist/chunks/api-KN24TLH6.js +2 -0
- package/dist/chunks/auth-VZSJMSMF.js +6 -0
- package/dist/chunks/azCli-AEZK2RBQ.js +2 -0
- package/dist/chunks/batch-EZPKLWEI.js +4 -0
- package/dist/chunks/build-LSQEAEFK.js +4 -0
- package/dist/chunks/bulk-7FZCDH5U.js +2 -0
- package/dist/chunks/chunk-4KP27OCL.js +2 -0
- package/dist/chunks/chunk-5SBBTR3Y.js +2 -0
- package/dist/chunks/chunk-B4FPKDMH.js +2 -0
- package/dist/chunks/chunk-BALEFXOL.js +29 -0
- package/dist/chunks/chunk-BCAXUZIO.js +2 -0
- package/dist/chunks/chunk-BODUSF3V.js +2 -0
- package/dist/chunks/chunk-C42MGXRN.js +2 -0
- package/dist/chunks/chunk-DVQ7OYIJ.js +2 -0
- package/dist/chunks/chunk-GE3XBV3K.js +2 -0
- package/dist/chunks/chunk-H4OY4EFC.js +3 -0
- package/dist/chunks/chunk-HIW2K6OP.js +4 -0
- package/dist/chunks/chunk-I3TMFYRJ.js +194 -0
- package/dist/chunks/chunk-J4R6QXW7.js +2 -0
- package/dist/chunks/chunk-JAGU2NM5.js +2 -0
- package/dist/chunks/chunk-JEAIFLEN.js +51 -0
- package/dist/chunks/chunk-KBQYSAJX.js +2 -0
- package/dist/chunks/chunk-LB7WNZVK.js +5 -0
- package/dist/chunks/chunk-LL4XQ3L7.js +4 -0
- package/dist/chunks/chunk-MBNUMAAZ.js +2 -0
- package/dist/chunks/chunk-MGZDEW3X.js +8 -0
- package/dist/chunks/chunk-MK6QZ4ES.js +2 -0
- package/dist/chunks/chunk-MTF66YXU.js +2 -0
- package/dist/chunks/chunk-MZEUD7ET.js +6 -0
- package/dist/chunks/chunk-OXZG44O5.js +2 -0
- package/dist/chunks/chunk-PYTSDUPY.js +2 -0
- package/dist/chunks/chunk-QMTPHZLQ.js +2 -0
- package/dist/chunks/chunk-RC5VPVGC.js +2 -0
- package/dist/chunks/chunk-S4KF5Z3S.js +10 -0
- package/dist/chunks/chunk-STWQDANK.js +5 -0
- package/dist/chunks/chunk-TADCW6ZI.js +2 -0
- package/dist/chunks/chunk-TM3M633T.js +3 -0
- package/dist/chunks/chunk-TQLZ3TRU.js +2 -0
- package/dist/chunks/chunk-TXVNEV3M.js +3 -0
- package/dist/chunks/chunk-TZSB4PR7.js +4 -0
- package/dist/chunks/chunk-UCTMKA2J.js +4 -0
- package/dist/chunks/chunk-WIA546AL.js +13 -0
- package/dist/chunks/chunk-WMDKJRDC.js +2 -0
- package/dist/chunks/chunk-WNQERCOO.js +2 -0
- package/dist/chunks/chunk-WXOTXJNG.js +3 -0
- package/dist/chunks/chunk-ZHHVG47C.js +2 -0
- package/dist/chunks/chunk-ZNJ4DRCA.js +2 -0
- package/dist/chunks/chunk-ZUXLC5VX.js +2 -0
- package/dist/chunks/commands-GRWX32IX.js +2 -0
- package/dist/chunks/component-TCL43QXZ.js +2 -0
- package/dist/chunks/components-LRHXR5HR.js +2 -0
- package/dist/chunks/config-UKI5TBH5.js +2 -0
- package/dist/chunks/connection-QNXMJGHZ.js +2 -0
- package/dist/chunks/connref-U3CMQ64O.js +2 -0
- package/dist/chunks/customizations-VNEASPWI.js +7 -0
- package/dist/chunks/dependency-U6OQA5PS.js +3 -0
- package/dist/chunks/discovery-IWAWXXWF.js +2 -0
- package/dist/chunks/dist-ILNYGTM2.js +136 -0
- package/dist/chunks/dv-C45WDXRG.js +192 -0
- package/dist/chunks/env-GL5ZPAZI.js +5 -0
- package/dist/chunks/environment-FPS4AFM5.js +2 -0
- package/dist/chunks/environments-VZWNFJYE.js +2 -0
- package/dist/chunks/envvar-52V6K6LF.js +2 -0
- package/dist/chunks/esm-Z4QMBGAD.js +2 -0
- package/dist/chunks/fanout-Q3656CCP.js +2 -0
- package/dist/chunks/fetchxml-FWUQZP4M.js +6 -0
- package/dist/chunks/functions-SNCK2IYV.js +2 -0
- package/dist/chunks/graph-OK24IOUV.js +5 -0
- package/dist/chunks/group-TLGLTTUG.js +6 -0
- package/dist/chunks/history-67SQS54S.js +2 -0
- package/dist/chunks/identity-SRTOEQVC.js +2 -0
- package/dist/chunks/jobs-2ZPBDDHT.js +2 -0
- package/dist/chunks/lifecycle-OJRM7K2I.js +2 -0
- package/dist/chunks/main-HOYSLMHZ.js +4 -0
- package/dist/chunks/metadata-WYVJ7NP7.js +2 -0
- package/dist/chunks/metadataCreate-PBA3KH3A.js +2 -0
- package/dist/chunks/msalUser-3PBGT655.js +2 -0
- package/dist/chunks/names-ZRM6SAYU.js +2 -0
- package/dist/chunks/pack-3OYGV36R.js +2 -0
- package/dist/chunks/pat-KGOBISLG.js +2 -0
- package/dist/chunks/pipelines-62CVDRXV.js +4 -0
- package/dist/chunks/plan-ALLKT2QZ.js +2 -0
- package/dist/chunks/plugins-SBMDFXVA.js +4 -0
- package/dist/chunks/policies-BZR5437X.js +2 -0
- package/dist/chunks/pools-I4NVR67Z.js +2 -0
- package/dist/chunks/process-WS76WV3T.js +2 -0
- package/dist/chunks/project-HSZLY2AY.js +2 -0
- package/dist/chunks/projects-GXIQO7HV.js +4 -0
- package/dist/chunks/protect-X2J7LU7X.js +2 -0
- package/dist/chunks/provider-FN7TXWRE.js +2 -0
- package/dist/chunks/prs-F2EVQJRV.js +2 -0
- package/dist/chunks/records-7IQET422.js +2 -0
- package/dist/chunks/run-APD3TRCW.js +2 -0
- package/dist/chunks/run-G2MVOV3C.js +3 -0
- package/dist/chunks/run-H2OLE76P.js +2 -0
- package/dist/chunks/run-ICS4FNZA.js +3 -0
- package/dist/chunks/run-KP2SNX2A.js +3 -0
- package/dist/chunks/run-LNEOCXZA.js +2 -0
- package/dist/chunks/run-SB4QN5Q4.js +2 -0
- package/dist/chunks/run-XRPU3YZF.js +2 -0
- package/dist/chunks/runtime-MIU5CS5B.js +2 -0
- package/dist/chunks/security-RC3EI7CZ.js +2 -0
- package/dist/chunks/service-4VHAPTA6.js +2 -0
- package/dist/chunks/service-RFKOKM72.js +2 -0
- package/dist/chunks/services-4BORTJPM.js +2 -0
- package/dist/chunks/skills-6O2GSTU4.js +2 -0
- package/dist/chunks/solution-3WUUDYF3.js +2 -0
- package/dist/chunks/solutionExport-GTBTHG2D.js +2 -0
- package/dist/chunks/solutionfiles-VWZHFZZ6.js +2 -0
- package/dist/chunks/spn-2RZJLCML.js +2 -0
- package/dist/chunks/tokenCache-TQFT6LAD.js +2 -0
- package/dist/chunks/unpack-HUH7OJMP.js +2 -0
- package/dist/chunks/users-JIBQKPYA.js +2 -0
- package/dist/chunks/vargroups-Q2KG7LHR.js +2 -0
- package/dist/chunks/whoami-V54TCLT5.js +2 -0
- package/dist/chunks/workitems-UG5O3EGB.js +2 -0
- package/dist/chunks/xmldoc-B2HUNTVK.js +2 -0
- package/package.json +57 -6
- package/schema/ppdo-cli.schema.json +132 -0
- package/skills/README.md +12 -0
- package/skills/ppdo-cli/SKILL.md +84 -0
- package/skills/ppdo-cli-dataverse/SKILL.md +302 -0
- package/skills/ppdo-cli-devops/SKILL.md +150 -0
|
@@ -0,0 +1,150 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: ppdo-cli-devops
|
|
3
|
+
description: Work with Azure DevOps through ppdo-cli - pull requests (create, review, comment, diff, link, auto-complete, complete), work items (query, saved queries, create, update, comment), pipelines and runs, repos (files, branches, commits, diffs, branch policies), PR policy checks, variable groups, and pipeline environments (approvals, checks, permissions). Also use it to investigate a failed pipeline run, a build results URL, or why a pipeline or deployment failed.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Azure DevOps with ppdo-cli
|
|
7
|
+
|
|
8
|
+
Load the ppdo-cli skill first (account, modes, exit codes, output). Ids can be given as numbers or as pasted `dev.azure.com` URLs; a URL from another organization or project is refused, so ask the user which configured environment to use. Text and bodies come from files: `--body @comment.md`, `--description @body.md`, `--wiql @query.wiql`, or `-` for stdin.
|
|
9
|
+
|
|
10
|
+
## Repos
|
|
11
|
+
|
|
12
|
+
```
|
|
13
|
+
ppdo-cli ado repo list [--limit n] [--all]
|
|
14
|
+
ppdo-cli ado repo get <name>
|
|
15
|
+
ppdo-cli ado repo file <repo> <path> [--ref <branch|refs/tags/name|sha>] [--save <file>]
|
|
16
|
+
ppdo-cli ado repo tree <repo> [<path>] [--ref <branch|refs/tags/name|sha>] [--one-level] [--limit n] [--all]
|
|
17
|
+
ppdo-cli ado repo branches <repo> [--name <pattern,…>] [--base <branch>] [--limit n] [--all]
|
|
18
|
+
ppdo-cli ado repo commits <repo> [<path>] [--ref <ref>] [--not-in <ref>] [--author <text>] [--since <when>] [--until <when>]
|
|
19
|
+
[--work-items] [--limit n] [--all]
|
|
20
|
+
ppdo-cli ado repo diff <repo> <base> <target> [--stat] [--file <path>] [--unified n] [--no-merge-base]
|
|
21
|
+
ppdo-cli ado repo policies <repo> [--branch <branch>]
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
- `repo file` / `repo tree`: read a repo without cloning it. Paths start at the repo root; write them without a leading `/` (Git Bash rewrites `/x` into a Windows path, which ppdo-cli refuses). `--ref` is a branch, `refs/tags/<name>`, or a full 40-character commit SHA (short SHAs aren't accepted); the default is the repo's default branch. `file` returns the `content` and the `commit` it was read at; `-o tsv` prints the raw text, and a binary file needs `--save`. `tree` lists every file and folder below the path, or only its direct children with `--one-level`.
|
|
25
|
+
- `repo branches`: each branch's latest `commit`, `author`, `updated` and `message`, newest first, with `ahead` and `behind`: commits it has that the default branch (marked `default`) doesn't, and the reverse. `--base` counts against another branch. `--name` takes `*` wildcards and `a,b`.
|
|
26
|
+
- `repo commits`: history like `git log`, newest first; without `--ref` it's the default branch. `<path>` keeps commits that changed a file or folder (renames aren't followed; a path that doesn't exist at the ref is a 404). `--not-in main` keeps the commits that aren't in main yet (`git log main..<ref>`). `--author` matches part of the name or email; `--since`/`--until` take `7d`, `12h` or a date and go by commit date. Each row has `commit`, `author`, `email`, `date` (authored), `committed` when it differs, `message` and `changes` (counts); `--work-items` adds linked work item ids.
|
|
27
|
+
- `repo diff <repo> <base> <target>`: what `<target>` changed since it split from `<base>`, like a PR (`git diff base...target`); `--no-merge-base` compares the two as they are. Start with `--stat`, then `--file`. JSON output adds `ahead`, `behind` and `merge_base`. Renames show as a delete and an add. Refs are written as for `repo file`.
|
|
28
|
+
- `repo policies`: branch policies (reviewers, build, linked work items, comments, merge strategy, status) and push restrictions (file size, file names, …). Each has `id`, `type`, `required` (blocking) or optional, `enabled`, `branches` (`main`, `release/*`, `(default branch)`; none for a push restriction), `all_repos` for a project-wide policy, and `settings` as Azure DevOps stores them, with `pipeline` and `reviewers` named. `--branch` keeps only what applies to that branch, project-wide policies included.
|
|
29
|
+
|
|
30
|
+
## Pull requests
|
|
31
|
+
|
|
32
|
+
```
|
|
33
|
+
ppdo-cli ado pr list [--repo <name>] [--status active|completed|abandoned|all] [--creator me|<upn>] [--reviewer me|<upn>] [--source <branch>] [--target <branch>]
|
|
34
|
+
[--limit n] [--all]
|
|
35
|
+
ppdo-cli ado pr get <pr>
|
|
36
|
+
ppdo-cli ado pr diff <pr> [--stat] [--file <path>] [--unified n]
|
|
37
|
+
ppdo-cli ado pr checks <pr> [--not-applicable]
|
|
38
|
+
ppdo-cli ado pr threads <pr> [--all]
|
|
39
|
+
ppdo-cli ado pr create --repo <name> --source <branch> --target <branch> --title <text> [--description @file] [--draft] [--work-item <id,…>]…
|
|
40
|
+
ppdo-cli ado pr update <pr> [--title <text>] [--description @file] [--draft | --publish]
|
|
41
|
+
ppdo-cli ado pr link <pr> --work-item <id,…>
|
|
42
|
+
ppdo-cli ado pr comment <pr> --body @file [--thread <id>] [--file <path> --line n [--end-line n]] [--status active|pending|fixed|wont-fix|closed|by-design]
|
|
43
|
+
ppdo-cli ado pr resolve <pr> <thread> [--status fixed|wont-fix|closed|by-design]
|
|
44
|
+
ppdo-cli ado pr auto-complete <pr> [--merge-strategy merge|squash|rebase|rebase-merge] [--delete-source-branch] [--transition-work-items]
|
|
45
|
+
[--message @file] [--ignore-policy <id,…>] [--conflict-authorship-commits] [--no-renames] | --off
|
|
46
|
+
ppdo-cli ado pr complete <pr> [--merge-strategy merge|squash|rebase|rebase-merge] [--delete-source-branch] [--transition-work-items]
|
|
47
|
+
[--message @file] [--conflict-authorship-commits] [--no-renames]
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
- `pr checks`: why a PR can or can't complete. Each policy has `status` (`approved`, `queued` (waiting, e.g. for votes), `running`, `rejected`, `broken`) and `blocks: true` when it's required and not yet approved; blocking ones come first. A build policy adds its `run` (`id` for `run logs --failed-only`, `expired`, `outdated`). `policy` is the id `pr auto-complete --ignore-policy` takes, for optional policies only. "Require a merge strategy" shows `rejected` until the PR has an allowed strategy (`pr auto-complete --merge-strategy`). Check this before `pr complete`, and after it exits 8.
|
|
51
|
+
- `pr list`: `--source` and `--target` take a branch name (or a full `refs/heads/…` ref), for example to check whether a branch already has an open PR into another.
|
|
52
|
+
- `pr diff`: start with `--stat` (changed files), then `--file <path>` for the files that matter; `--unified n` sets context lines (default 3).
|
|
53
|
+
- `pr threads`: review comments only; `--all` adds system threads (votes, pushes).
|
|
54
|
+
- `pr create`: `--work-item` links work items (repeatable); a `#123` mention in the text links nothing. Descriptions are limited to 4000 characters.
|
|
55
|
+
- `pr comment`: `--thread` replies to a thread; `--file` with `--line` (and `--end-line` for a range) starts a thread on a file; `--status` sets the new thread's status. `pr resolve` changes a thread's status (`fixed` shows as Resolved).
|
|
56
|
+
- `pr update`: `--draft`/`--publish` move a PR between draft and published. Changing the description of an auto-completing PR doesn't change its merge commit message; set that with `pr auto-complete --message`.
|
|
57
|
+
- `pr link` and `wi link --pr` add the formal PR link (a `#123` mention doesn't). `wi link --commit` needs the full 40-character SHA with `--repo`, or the commit's URL.
|
|
58
|
+
- `pr auto-complete` and `pr complete`: options the PR already has are kept unless given. `merge` is a no-fast-forward merge; `--transition-work-items` moves linked work items on; `--ignore-policy` takes optional policy ids not to wait for; `--conflict-authorship-commits` and `--no-renames` are merge options. Neither command ever bypasses branch policies: a required policy that isn't passing stops `complete` with exit 8, so report what's missing (approvals, builds) instead of looking for a way round it. `complete` waits up to a minute for the merge and returns the merge commit.
|
|
59
|
+
|
|
60
|
+
## Work items
|
|
61
|
+
|
|
62
|
+
```
|
|
63
|
+
ppdo-cli ado wi get <id> [--fields a,b] [--relations]
|
|
64
|
+
ppdo-cli ado wi query --wiql @file | --saved <query id> [--fields a,b] [--limit n] [--all]
|
|
65
|
+
ppdo-cli ado wi queries [<folder>] [--name <text>] [--wiql] [--limit n] [--all]
|
|
66
|
+
ppdo-cli ado wi create --type <type> --title <text> [--field name=value|name=@file]… [--parent <id>] [--assign <upn>] [--html]
|
|
67
|
+
ppdo-cli ado wi link <id> --pr <pr> | --commit <sha|url> [--repo <name>]
|
|
68
|
+
ppdo-cli ado wi update <id> [--field name=value|name=@file]… [--state <state>] [--title <text>] [--assign <upn>]
|
|
69
|
+
[--add-tag a,b]… [--remove-tag a,b]… [--html]
|
|
70
|
+
ppdo-cli ado wi tags [--limit n] [--all]
|
|
71
|
+
ppdo-cli ado wi attachments <id> [--name <pattern,…>] [--save <dir>]
|
|
72
|
+
ppdo-cli ado wi comment <id> --body @file [--html] | --edit <comment> --body @file [--html] | --delete <comment>
|
|
73
|
+
ppdo-cli ado wi fields --type <type> [--name <pattern,…>] [--required]
|
|
74
|
+
ppdo-cli ado wi comments <id> [--reactions] [--limit n] [--all]
|
|
75
|
+
ppdo-cli ado wi react <id> <comment> like|dislike|heart|hooray|smile|confused [--remove]
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
- `wi`: field names are `Title`, `State`, `Priority`, `StoryPoints` … or full reference names. `--fields` picks the fields returned; `get --relations` adds links; `create --parent` links a parent.
|
|
79
|
+
- `wi create`/`update`/`comment` write Markdown: long-text fields (`Description`, `ReproSteps`, `AcceptanceCriteria`, `History`, custom HTML fields) and comments. Write Markdown, not HTML; `--html` is only for text that is already HTML. A field takes the format of the value written to it, so updating an HTML description converts it to Markdown. Put long text in a file: `--field Description=@desc.md`. `wi get` lists the long-text fields stored as Markdown under `formats`; one that isn't listed is HTML, so read it as HTML.
|
|
80
|
+
- `wi fields --type <type>`: what a work item type can hold, before `wi create` or `update`. For a type's states, use `wi fields --type <type> --name State`, not the API. `--name` takes a field's name or reference name, with `*` wildcards and `a,b` for several. Each field has `name`, `reference_name`, `type` and `required`, and when they apply `default`, `allowed_values` (a dropdown's choices; State's in workflow order, with each state's category under `states`), `other_values_allowed`, `long_text` (written as Markdown), `identity` (a user's UPN) and `read_only`. Area ID and Iteration ID show as required but are filled in from the paths. Fields differ between processes, so check before setting one (Basic has no Acceptance Criteria). There is no multi-select field type: Tags is free text separated by `;`.
|
|
81
|
+
- Tags: `wi tags` lists the project's tags; reuse one rather than inventing a near-duplicate (matching ignores case). `wi update --add-tag`/`--remove-tag` change only the tags named and keep the rest; `--field Tags=…` replaces all of them. A removal that races another change exits 6 (run it again). Azure DevOps stores tags in alphabetical order.
|
|
82
|
+
- `wi attachments`: the files attached to a work item (`id`, `name`, `size` in bytes, `added`, `comment`). `--save <dir>` downloads them and adds each one's `file`; a second file with the same name is saved as `name (2).ext`. `--name` picks files (`*` wildcards, `a,b`). Images pasted into a description or comment aren't attachments and aren't listed.
|
|
83
|
+
- `wi queries`: saved queries (`Shared Queries` and `My Queries`) with their `id` for `wi query --saved`, `path`, `type` (`flat`, `tree`, `oneHop`) and `shared`. `<folder>` lists one folder's queries; `--name` finds names containing the text at any depth; `--wiql` adds the WIQL. Run a query the team already keeps rather than writing your own WIQL.
|
|
84
|
+
- `wi comment --edit <comment>` replaces a comment's text (Markdown unless `--html`, like a new comment); `--delete <comment>` deletes it and needs mode `full`. Only a comment's author can edit or delete it: someone else's exits 8.
|
|
85
|
+
- `wi comments`: the discussion, newest first, each with `author`, `created`, `modified` (when edited), `format` and `text`; deleted comments are left out. `wi get` doesn't include comments. `--reactions` adds `reactions` (count by type, e.g. `{"like": 2}`) and `reacted` (the ones you added) to every comment.
|
|
86
|
+
- `wi react`: `<comment>` is an `id` from `wi comments`. It returns the reaction's `count` and whether you've `reacted`; adding the same reaction again changes nothing. `--remove` takes yours away and needs mode `full` (it is an HTTP DELETE).
|
|
87
|
+
|
|
88
|
+
## Pipelines and runs
|
|
89
|
+
|
|
90
|
+
```
|
|
91
|
+
ppdo-cli ado pipeline list [--folder <path>] [--limit n] [--all]
|
|
92
|
+
ppdo-cli ado pipeline get <pipeline>
|
|
93
|
+
ppdo-cli ado pipeline stages <pipeline> [--branch <ref>] [--param k=v]…
|
|
94
|
+
ppdo-cli ado pipeline run <pipeline> [--branch <ref>] [--param k=v]… [--variable k=v]… [--skip-stage <a,b> | --only-stage <a,b>]
|
|
95
|
+
[--wait] [--logs-on-failure]
|
|
96
|
+
ppdo-cli ado run list <pipeline> [--branch <ref>] [--result succeeded|partiallySucceeded|failed|canceled]
|
|
97
|
+
[--reason manual,schedule,individualCI,pullRequest,…] [--limit n] [--all]
|
|
98
|
+
ppdo-cli ado run get <run>
|
|
99
|
+
ppdo-cli ado run logs <run> [--failed-only] [--step <name>] [--tail n] [--timestamps] [--save <dir>]
|
|
100
|
+
ppdo-cli ado run retry <run> [--stage <a,b>] [--all-jobs] [--wait] [--logs-on-failure]
|
|
101
|
+
ppdo-cli ado run cancel <run>
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
- `pipeline stages`: the stages a run would have (`name`, `display_name`, `depends_on`, `condition`), from a preview of the expanded YAML; nothing is queued, so it works in read-only groups. Pass the same `--branch` and `--param` as the run.
|
|
105
|
+
- `pipeline run`: `--param` sets YAML parameters, `--variable` runtime variables. `--skip-stage` leaves stages out and `--only-stage` runs only those named (stage name or display name, checked against `pipeline stages`); a skipped stage doesn't stop the stages that depend on it, so skip those too if they shouldn't run. `--wait` waits and exits non-zero unless the run succeeds; `--logs-on-failure` adds the failed steps' log tails.
|
|
106
|
+
- `<run>` is a run id or a pasted build results URL. `run get`: status, stages (each with its `attempt`), and the `errors` from the timeline.
|
|
107
|
+
- `run logs`: `--failed-only` shows only failed steps; `--step` matches step names containing the text; `--tail n` sets lines per step (default 100, `0` for all); `--timestamps` keeps each line's timestamp. `--save <dir>` writes each step's whole log (or `--tail n` lines) to `<dir>/<job>-<step>.log` and prints the file paths instead of the logs; use it for long logs, then read or search the files.
|
|
108
|
+
- `run retry`: re-runs the failed or canceled stages of a finished run (or `--stage`, by name or display name); only the failed jobs run again unless `--all-jobs`. The run keeps its id.
|
|
109
|
+
- `run list`: `--reason` keeps runs by what triggered them: `manual`, `schedule`, `individualCI` or `batchedCI` (a push), `pullRequest`, `resourceTrigger`, `buildCompletion`, and a few rarer ones (`--help` lists them). Each run's `reason` is in the output.
|
|
110
|
+
|
|
111
|
+
### A failed run
|
|
112
|
+
|
|
113
|
+
1. `ppdo-cli ado run get <run>`. The timeline errors often explain the failure without any logs.
|
|
114
|
+
2. `ppdo-cli ado run logs <run> --failed-only`. Use `--tail 400` or `--step "<name>"` to see more of one step, or `--save <dir>` for whole logs.
|
|
115
|
+
3. Read the error text before guessing, and report plainly: which stage and step failed, the error, the likely cause and the fix, quoting the decisive log lines.
|
|
116
|
+
|
|
117
|
+
Don't re-run anything unless the user asks. When they do, `run retry <run> --wait` re-runs only what failed (a transient failure, or after a fix outside the pipeline), `pipeline run … --wait` starts a new run (after a code fix), and `run cancel <run>` stops one. If a run sat queued for a long time, check the agent pool with `pool usage <pool> --since 1d`. For a Dataverse solution import that failed inside a pipeline, the import job keeps the details: `ppdo-cli dv solution import-results <solution>` (see the ppdo-cli-dataverse skill).
|
|
118
|
+
|
|
119
|
+
## Variable groups, environments and pools
|
|
120
|
+
|
|
121
|
+
```
|
|
122
|
+
ppdo-cli ado vargroup list [--name <pattern>] [--limit n] [--all]
|
|
123
|
+
ppdo-cli ado vargroup get <group>
|
|
124
|
+
ppdo-cli ado vargroup create <name> [--variable k=v|k=@file]… [--secret k=v|k=@file]… [--description <text>]
|
|
125
|
+
ppdo-cli ado vargroup set <group> [--variable k=v|k=@file]… [--secret k=v|k=@file]… [--remove <name>]… [--description <text>]
|
|
126
|
+
ppdo-cli ado environment list [--name <pattern>] [--limit n] [--all]
|
|
127
|
+
ppdo-cli ado environment create <name> [--description <text>]
|
|
128
|
+
ppdo-cli ado environment checks <environment>
|
|
129
|
+
ppdo-cli ado environment permit <environment> --pipeline <id|name|url>
|
|
130
|
+
ppdo-cli ado pool list [--name <pattern>] [--legacy] [--limit n] [--all]
|
|
131
|
+
ppdo-cli ado pool agents <pool> [--status online|offline]
|
|
132
|
+
ppdo-cli ado pool usage <pool> [--since <when>] [--limit n] [--top n]
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
- `vargroup get`: secret values are never shown. `--name` takes a trailing `*` wildcard.
|
|
136
|
+
- `vargroup create`/`set`: Azure DevOps replaces the whole group on every write, so `set` sends back every variable it isn't changing and leaves secrets as they are. A secret can't be made plain or empty (refused). Read secret values from a file (`--secret token=@token.txt`) so they don't appear in the command; `--dry-run` hides them.
|
|
137
|
+
- `pool usage`: from the pool's job history (about 40 days are kept): how long jobs waited for an agent (`wait_seconds` average, p50, p95, max), how long they ran, the most running at once (`peak_concurrent`, against the pool's `agents`), and the busiest pipelines. A peak equal to the agent count with a high p95 wait is the evidence for more agents. `--since` defaults to 7 days.
|
|
138
|
+
- `environment` is a pipeline environment (deployment target), not a ppdo-cli environment. `checks` shows its approvals and checks and which pipelines may use it; `permit` lets a pipeline deploy to it without waiting for permission.
|
|
139
|
+
|
|
140
|
+
## Projects, users and the raw API
|
|
141
|
+
|
|
142
|
+
```
|
|
143
|
+
ppdo-cli ado project list [--limit n] [--all]
|
|
144
|
+
ppdo-cli ado user get <email|upn|name|me>
|
|
145
|
+
ppdo-cli ado api <METHOD> <path> [--body @file] [--header k:v]… [--param k=v]… [--api-version <v>]
|
|
146
|
+
[--host core|vssps|vsrm|analytics|feeds|pkgs|vsaex] [--paginate] [--limit n] [--save <file>]
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
- `user get`: checks that someone exists in the organization before you assign or mention them, and returns `id`, `name`, `upn`, `mail`, `descriptor`, `active`, `kind` (User or Group) and `object_id`. Matching is exact (email, UPN or full display name, ignoring case); part of a name finds nobody (exit 4). Groups work as `[project]\Group`. `me` is the signed-in account.
|
|
150
|
+
- `api`: any REST request, relative to `https://dev.azure.com/<org>/`; `{project}` in the path is the environment's project. `--api-version` defaults to 7.1, `--host` picks another DevOps host, `--paginate` follows continuation tokens.
|