python-gitea 0.10.1__tar.gz → 0.11.0__tar.gz

{python_gitea-0.10.1 → python_gitea-0.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: python-gitea
-Version: 0.10.1
+Version: 0.11.0
 Summary: A Python package for interacting with the Gitea API, offering a simple interface to access repositories, users, organizations, issues, and more for automation and data management.
 Project-URL: Documentation, https://isaac-cf-wong.github.io/python-gitea
 Project-URL: Source, https://github.com/isaac-cf-wong/python-gitea
@@ -36,6 +36,7 @@ Description-Content-Type: text/markdown
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/isaac-cf-wong/python-gitea/blob/main/LICENSE)
 [![Security: bandit](https://img.shields.io/badge/security-bandit-yellow.svg)](https://github.com/PyCQA/bandit)
 [![DOI](https://zenodo.org/badge/1129170965.svg)](https://doi.org/10.5281/zenodo.18211496)
+[![SPEC 0 — Minimum Supported Dependencies](https://img.shields.io/badge/SPEC-0-green?labelColor=%23004811&color=%235CA038)](https://scientific-python.org/specs/spec-0000/)
 
 A Python package for interacting with the Gitea API. It provides a simple,
 intuitive interface to access Gitea repositories, users, organizations, issues,
@@ -45,7 +46,8 @@ data retrieval, and management tasks.
 ## Features
 
 - **Full API Coverage**: Repositories, users, organizations, issues, pull
-  requests, comments, labels, milestones, notifications, and projects.
+  requests, comments, labels, milestones, notifications, projects, and Actions
+  workflows, runs, and job logs.
 - **Easy Authentication**: Token-based authentication, with multiple saved
   accounts and a default-account fallback.
 - **Asynchronous Support**: Built with `async`/`await` for non-blocking

{python_gitea-0.10.1 → python_gitea-0.11.0}/README.md

@@ -9,6 +9,7 @@
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/isaac-cf-wong/python-gitea/blob/main/LICENSE)
 [![Security: bandit](https://img.shields.io/badge/security-bandit-yellow.svg)](https://github.com/PyCQA/bandit)
 [![DOI](https://zenodo.org/badge/1129170965.svg)](https://doi.org/10.5281/zenodo.18211496)
+[![SPEC 0 — Minimum Supported Dependencies](https://img.shields.io/badge/SPEC-0-green?labelColor=%23004811&color=%235CA038)](https://scientific-python.org/specs/spec-0000/)
 
 A Python package for interacting with the Gitea API. It provides a simple,
 intuitive interface to access Gitea repositories, users, organizations, issues,
@@ -18,7 +19,8 @@ data retrieval, and management tasks.
 ## Features
 
 - **Full API Coverage**: Repositories, users, organizations, issues, pull
-  requests, comments, labels, milestones, notifications, and projects.
+  requests, comments, labels, milestones, notifications, projects, and Actions
+  workflows, runs, and job logs.
 - **Easy Authentication**: Token-based authentication, with multiple saved
   accounts and a default-account fallback.
 - **Asynchronous Support**: Built with `async`/`await` for non-blocking

{python_gitea-0.10.1 → python_gitea-0.11.0}/docs/dev/architecture.md

@@ -35,6 +35,15 @@ src/gitea/
 │   └── manager.py           # ConfigManager (load/save/CRUD accounts)
 ├── resource/                # Resource base class
 │   └── resource.py          # Shared request helpers for resources
+├── actions/                 # Actions resource (sync + async), composed per family
+│   ├── base.py              # Every Actions path and query parameter
+│   ├── scope.py             # Which scope a set of coordinates addresses
+│   ├── actions.py           # Workflows, runs, jobs; composes the families below
+│   ├── run_management.py    # Cancel, approve, rerun, delete a run
+│   ├── artifact.py          # The files a run produced, archive included
+│   ├── secret.py            # Write-only secrets of a scope
+│   ├── variable.py          # Their readable counterpart
+│   └── runner.py            # Runners of a scope, and the registration token
 ├── issue/                   # Issue resource (sync + async)
 ├── pull_request/            # Pull request resource (sync + async)
 ├── repository/              # Repository resource (sync + async)
@@ -48,6 +57,7 @@ src/gitea/
 ├── cli/                     # Typer CLI application
 │   ├── main.py              # gitea-cli entry point, command registration
 │   ├── config/              # config commands
+│   ├── actions/             # actions workflow, run, job, artifact, secret, variable, runner commands
 │   ├── issue/               # issue + issue dependency commands
 │   ├── pull_request/        # pull-request commands
 │   ├── comment/             # comment commands
@@ -80,6 +90,7 @@ Each client exposes one attribute per resource:
 
 ```python
 with Gitea(token="...", base_url="...") as client:
+    client.actions        # Actions
     client.issue          # Issue
     client.pull_request   # PullRequest
     client.repository     # Repository
@@ -107,6 +118,34 @@ it, so the resource methods stay one-to-one with the API. For example,
 `gitea.issue.project_column` resolves the board column an issue's card sits in,
 which Gitea only reveals through the project's column listings.
 
+`actions` is the one resource split further, into a module per family - runs,
+artifacts, secrets, variables, runners - which `Actions` and `AsyncActions`
+compose. Gitea's Actions API is large enough that one class per client would be
+a file nobody reads end to end, and the families differ from each other in ways
+worth writing down beside their own methods: which listings answer with an
+object and which with a bare array, which endpoints answer with a file rather
+than a document, and which scopes each family exists at. The path building for
+all of them stays in one `base.py`, so every URL the resource can address is in
+one place.
+
+That package's `__init__.py` re-exports nothing, unlike its neighbours'. With
+thirteen modules an eager re-export would make `import gitea.actions.scope`
+execute all of them, and would put each in an import cycle: importing a
+submodule imports its package, so a package that imports its submodules is one
+they import back. `tests/actions/test_actions_imports.py` pins both properties.
+
+The neighbours keep their re-exports and avoid the same two costs by resolving
+them on first read instead, through a module-level `__getattr__` (PEP 562) that
+`gitea._lazy.lazy_reexports` builds from a table of name against origin module.
+`from gitea.issue import Issue` works exactly as it did, while
+`import gitea.issue.base` no longer executes either client - and the package no
+longer imports the submodules that import it back, which is where 44 of the
+import cycles in this tree came from. Each such package keeps a `TYPE_CHECKING`
+block naming the same imports, so editors and type checkers still resolve the
+names statically; that block does not execute, so it reintroduces no cycle.
+`tests/test_lazy_reexports.py` pins the public names, the laziness, and the
+absence of any module-level import cycle anywhere in `gitea`.
+
 ## CLI Layer
 
 The CLI is a single Typer application registered in `cli/main.py`. Each resource

{python_gitea-0.10.1 → python_gitea-0.11.0}/docs/user-guide/cli.md

@@ -126,9 +126,18 @@ way, so an invocation can be written without reading `--help` first:
 | `--owner`       | The user or organization that owns the target. Required. |
 | `--repository`  | Narrows the target to one repository of that owner.      |
 | `--<entity>-id` | Names the entity acted on.                               |
+| `--admin`       | Asks for the instance-wide form, where one exists.       |
 
-The entity options are `--issue-id`, `--project-id`, `--column-id`, `--label-id`
-and `--comment-id`.
+The entity options are `--issue-id`, `--project-id`, `--column-id`,
+`--label-id`, `--comment-id`, `--workflow-id`, `--run-id`, `--job-id`,
+`--artifact-id` and `--runner-id`. Two entities Gitea addresses by name rather
+than by number - an Actions secret and an Actions variable - are named by
+`--secret-name` and `--variable-name`, since `--secret-id` would promise a
+number the API does not have.
+
+`--admin` is offered by the Actions commands whose endpoint has an instance-wide
+form. It belongs to no owner, so it cannot be combined with `--owner`, and it
+needs an administrator's token. See [the Actions scopes](#actions-scopes).
 
 Omitting `--repository` asks for the target that belongs to the owner itself
 rather than to one of its repositories. The `project` commands have both forms:
@@ -138,6 +147,9 @@ gitea-cli project get --owner my-org --project-id 1                      # organ
 gitea-cli project get --owner my-org --repository my-repo --project-id 1  # repository project
 ```
 
+Most of the Actions commands have both forms too, and some have four: see
+[the Actions scopes](#actions-scopes) for the table.
+
 The other families have no owner-wide endpoint - an issue, a comment, a label, a
 milestone and a pull request all live in a repository - so omitting
 `--repository` there is reported as an error naming the option to pass:
@@ -205,6 +217,224 @@ endpoint to serve it with, so they answer by naming the option to pass.
     - Under `--output json` the confirmation prompt is written to stderr so that
       stdout stays parsable; pass `--force` to skip it entirely.
 
+### Actions - run, inspect and configure workflows
+
+A workflow is the file in the repository and what is dispatched, a run is one
+execution of it and what carries the status, a job is a part of a run and what
+carries the logs, and an artifact is a file a job produced. The commands are
+grouped that way. Three further groups configure Actions rather than watch it: a
+`secret` and a `variable` are what a workflow reads at run time, and a `runner`
+is a machine that executes jobs.
+
+`--workflow-id` is the workflow's **file name** - `build.yml` - and not a
+number: that is what Gitea's endpoint takes. `--run-id` and `--job-id` are IDs,
+as everywhere else.
+
+- `gitea-cli actions workflow list --owner <owner> --repository <repo>`
+- `gitea-cli actions workflow get --owner <owner> --repository <repo> --workflow-id <file>`
+- `gitea-cli actions workflow dispatch --owner <owner> --repository <repo> --workflow-id <file> --ref <ref>`
+    - Optional: `--input KEY=VALUE` (repeatable), `--return-run-details`
+    - The workflow has to declare a `workflow_dispatch` trigger: that is the
+      trigger a dispatch fires, so a workflow without one has nothing for this
+      to start.
+    - Gitea accepts a dispatch with `204` and no body, which says the request
+      was taken but not which run it started. `--return-run-details` asks the
+      response to name the run - `workflow_run_id`, `run_url`, `html_url` - so a
+      script can follow the run it dispatched instead of guessing which of the
+      runs that appeared is its own. An instance too old to know the parameter
+      answers without a body as before, so treat an empty `data` as "accepted,
+      run not named" rather than as a failure.
+    - Only the first `=` of an `--input` divides the name from the value, so
+      `--input query=a=b` sets `query` to `a=b`. An input given twice with two
+      different values is refused rather than one of them silently kept.
+- `gitea-cli actions run list --owner <owner> --repository <repo>`
+    - Optional: `--workflow-id`, `--admin`, `--event`, `--branch`, `--status`,
+      `--actor`, `--head-sha`, `--exclude-pull-requests`, `--page`, `--limit`
+    - `--status` is one of `pending`, `queued`, `in_progress`, `failure`,
+      `success`, `skipped`.
+    - `--workflow-id` asks a different endpoint - the workflow's own runs -
+      rather than filtering the repository's.
+    - This listing exists at four [scopes](#actions-scopes). `--workflow-id` and
+      `--exclude-pull-requests` belong to the repository form alone, and passing
+      either outside a repository is refused rather than quietly ignored.
+- `gitea-cli actions run get --owner <owner> --repository <repo> --run-id <id>`
+    - `status` says how far the run has got, `conclusion` how it ended. A run
+      still going has no conclusion yet.
+- `gitea-cli actions run jobs --owner <owner> --repository <repo> --run-id <id>`
+    - Optional: `--status`, `--page`, `--limit`
+- `gitea-cli actions job get --owner <owner> --repository <repo> --job-id <id>`
+    - The job carries its `steps`, each with a `status` and a `conclusion`,
+      which is where a failure is narrowed to the step that failed.
+- `gitea-cli actions job logs --owner <owner> --repository <repo> --job-id <id>`
+    - Text output is the log itself, so it can be piped, grepped or redirected
+      like the file it is; `--output json` wraps it in the envelope instead,
+      with the log as a string under `logs` and `job_id` alongside it. A job
+      that has produced nothing yet prints nothing.
+- `gitea-cli actions job list --owner <owner> --repository <repo>`
+    - Optional: `--admin`, `--status`, `--page`, `--limit`
+    - A different endpoint from `run jobs`: it answers with **every** job of the
+      scope rather than the jobs of one run, so `--status queued` finds what is
+      waiting for a runner without walking the runs to reach it. Exists at four
+      [scopes](#actions-scopes).
+
+These listings answer with an **object** and not with the bare array the other
+listings in this CLI return: `total_count` alongside `workflows`,
+`workflow_runs` or `jobs`. That is the shape Gitea's Actions endpoints send, and
+[the field-name convention](#field-names) is why it is passed through rather
+than flattened. So a script reads `.data.workflow_runs[]` where it would read
+`.data[]` for issues. One page is fetched per invocation; `--page` and `--limit`
+walk a long history.
+
+#### Acting on a run
+
+- `gitea-cli actions run cancel --owner <owner> --repository <repo> --run-id <id>`
+    - Asks the run's jobs to stop and waits for them to notice. A job whose
+      runner has gone away never does, and the run then stays `in_progress`.
+- `gitea-cli actions run force-cancel --owner <owner> --repository <repo> --run-id <id>`
+    - Marks the run cancelled regardless, which is what clears a stuck one. It
+      is a different endpoint and not a retry of `cancel`: a job that really is
+      still running somewhere is disowned rather than stopped, so cancel first
+      and reach for this when that has not taken effect.
+- `gitea-cli actions run approve --owner <owner> --repository <repo> --run-id <id>`
+    - A run triggered by a first-time contributor's pull request waits for
+      someone with write access and shows as `blocked` until then.
+- `gitea-cli actions run rerun --owner <owner> --repository <repo> --run-id <id>`
+    - Optional: `--failed-jobs`
+    - `--failed-jobs` reruns only the jobs that failed, which is a different
+      endpoint and the one for a long run that failed on one flaky job: the jobs
+      that succeeded keep their results. It answers without a body, so an empty
+      `data` there is a rerun that started.
+- `gitea-cli actions job rerun --owner <owner> --repository <repo> --run-id <id> --job-id <id>`
+    - Reruns one named job. This is the one job command that takes the run as
+      well, because Gitea addresses the rerun through the run.
+- `gitea-cli actions run delete --owner <owner> --repository <repo> --run-id <id>`
+    - Deletes the run **and** the jobs, logs and artifacts it produced, which is
+      how a repository is cleared of those rather than only of the run's entry.
+      A run that has not finished cannot be deleted; cancel it first.
+
+Cancelling, approving and rerunning answer with the run as it now stands, so
+`.data.status` says what the request did rather than only that it was taken.
+
+#### Artifacts
+
+An artifact is a file a job uploaded. Uploading one is not offered here and is
+not an omission: Gitea has no REST endpoint for it - an artifact is uploaded
+from inside a running job, by the runner, over the Actions protocol.
+
+- `gitea-cli actions artifact list --owner <owner> --repository <repo>`
+    - Optional: `--run-id`, `--name`
+    - `--run-id` asks the run's own artifacts, a different endpoint rather than
+      a filter. `--name` narrows rather than identifies: a run uploading one
+      artifact per job has several of the same name.
+    - Answers with an object: `total_count` alongside `artifacts`.
+- `gitea-cli actions artifact get --owner <owner> --repository <repo> --artifact-id <id>`
+    - `size_in_bytes` sizes a download and `expired` says whether there is an
+      archive left to download at all.
+- `gitea-cli actions artifact download --owner <owner> --repository <repo> --artifact-id <id> --file <path>`
+    - Optional: `--force`
+    - Writes the zip to `--file`; it is never written to stdout, since a zip
+      interleaved with the JSON envelope would be neither. `--force` overwrites
+      an existing file, and without it an existing path is refused. An artifact
+      whose archive has expired is reported rather than saved as a zero-byte
+      file.
+    - `data` names where the archive went and how large it was - `path` and
+      `size_in_bytes` - since the response itself carries no field saying
+      either.
+- `gitea-cli actions artifact delete --owner <owner> --repository <repo> --artifact-id <id>`
+    - Deletes the archive; the run it belongs to stays, and keeps its logs.
+
+#### Secrets, variables and runners
+
+<a id="actions-scopes"></a> These three, and the `run list` and `job list`
+commands, exist at more than one **scope**, and which one is asked for follows
+[the naming convention](#option-naming):
+
+| Coordinates                  | Scope                     | Path                                |
+| ---------------------------- | ------------------------- | ----------------------------------- |
+| `--owner` and `--repository` | that repository           | `/repos/{owner}/{repo}/actions/...` |
+| `--owner` alone              | that organization         | `/orgs/{owner}/actions/...`         |
+| neither                      | the authenticated account | `/user/actions/...`                 |
+| `--admin`                    | the whole instance        | `/admin/actions/...`                |
+
+`--owner` alone is the **organization** form, not a generic owner form: Gitea
+answers it only for an organization. `--admin` needs an administrator's token
+and cannot be combined with `--owner`.
+
+Not every group offers every scope. A secret cannot be _listed_ for the
+authenticated account, and neither secrets nor variables have an instance-wide
+form. Asking for a scope that does not exist is refused by name rather than
+answered with an empty listing, which is what the missing endpoint would
+otherwise look like.
+
+- `gitea-cli actions secret list --owner <owner> [--repository <repo>]`
+    - Optional: `--page`, `--limit`
+    - A secret's value is never listed: Gitea stores it write-only, so the
+      entries carry the name, the description and when it was set. Answers with
+      a **bare array**, unlike the other Actions listings.
+    - A job sees the secrets of every scope above it, so a repository's listing
+      is not the set of secrets its workflows can read.
+- `gitea-cli actions secret set --secret-name <name> --data <value> [--owner <owner>] [--repository <repo>]`
+    - Optional: `--description`
+    - `--data -` reads the value from **stdin**, which is the spelling to use
+      anywhere the value matters: a value on the command line is in the shell
+      history and in the process list of the machine it ran on. Exactly one
+      trailing newline is stripped, so `echo` and `printf` both send what they
+      look like they send.
+    - One endpoint creates and replaces. Gitea answers `201` when the secret was
+      new and `204` when it replaced one, so `.metadata.status_code` is what
+      says which happened; both are success.
+    - Omitting `--description` leaves the existing one rather than clearing it.
+- `gitea-cli actions secret delete --secret-name <name> [--owner <owner>] [--repository <repo>]`
+- `gitea-cli actions variable list [--owner <owner>] [--repository <repo>]`
+    - Optional: `--page`, `--limit`
+    - The readable counterpart of a secret: the value comes back, under `data`.
+      Anything a workflow must not print belongs in a secret instead. Answers
+      with a bare array.
+- `gitea-cli actions variable get --variable-name <name> [--owner <owner>] [--repository <repo>]`
+- `gitea-cli actions variable create --variable-name <name> --value <value> [--owner <owner>] [--repository <repo>]`
+    - Optional: `--description`
+    - A name that already exists is a conflict rather than an overwrite, so this
+      is safe to retry against a name believed to be free.
+- `gitea-cli actions variable update --variable-name <name> --value <value> [--owner <owner>] [--repository <repo>]`
+    - Optional: `--new-name`, `--description`
+    - `--value` is required even by an update that only means to rename: Gitea
+      requires the value in the body, so read it with `variable get` first
+      rather than guessing it. `--new-name` is the rename; omitting it leaves
+      the name alone.
+- `gitea-cli actions variable delete --variable-name <name> [--owner <owner>] [--repository <repo>]`
+- `gitea-cli actions runner list [--owner <owner>] [--repository <repo>] [--admin]`
+    - Optional: `--state enabled|disabled`
+    - A runner is registered to one scope and then runs the jobs of everything
+      under it, so a scope's listing shows the runners registered **there** -
+      not every runner that could pick up its jobs. A repository whose jobs all
+      run on an organization runner has an empty listing of its own, and that is
+      not a repository with nowhere to run.
+    - `status` says whether the runner is reachable and `busy` whether it is
+      running something; both are independent of `--state`, since a runner can
+      be online and disabled at once and then takes no jobs. Answers with an
+      object: `total_count` alongside `runners`.
+- `gitea-cli actions runner get --runner-id <id> [--owner <owner>] [--repository <repo>] [--admin]`
+    - `labels` is what a job's `runs-on` is matched against, and is the usual
+      reason a job sits queued while a runner sits idle.
+    - A runner is addressed through the scope it is registered to, so a real
+      runner asked for through another scope is reported as not found.
+- `gitea-cli actions runner update --runner-id <id> --state enabled|disabled [--owner <owner>] [--repository <repo>] [--admin]`
+    - `--state` is Gitea's `disabled` field, named rather than offered as a
+      flag: there is no partial update of a runner, so an update says which of
+      the two states it means rather than defaulting to one. Disabling is the
+      reversible alternative to `runner delete`.
+- `gitea-cli actions runner delete --runner-id <id> [--owner <owner>] [--repository <repo>] [--admin]`
+    - Removes the registration. A runner process still running keeps trying to
+      poll and is refused, so a machine meant to come back has to re-register.
+- `gitea-cli actions runner registration-token [--owner <owner>] [--repository <repo>] [--admin]`
+    - The token `act_runner register` is given. Registering a runner is not
+      something this API does: take the token here, register the machine out of
+      band, then list what appeared.
+    - The token belongs to the **scope** and not to one runner, and it is a
+      credential: anything holding it can attach a machine that will execute the
+      scope's jobs. It is printed, so redirect it rather than leaving it in a
+      shell history or a CI log.
+
 ### Issue - manage issues
 
 - `gitea-cli issue create --owner <owner> --repository <repo> --title <title>`
@@ -325,8 +555,11 @@ gitea-cli project list --owner my-org --repository my-repo  # that repository's
       arrived in `--column-id`. An issue with no card there is reported as an
       error naming `project issue add`; `--add-if-missing` has this command put
       it in `--column-id` instead.
-- `gitea-cli project issue remove --owner <owner> [--repository <repo>] --project-id <id> --column-id <id> --issue-id <id>`
-    - Optional: `--issue-repository`
+- `gitea-cli project issue remove --owner <owner> [--repository <repo>] --project-id <id> --issue-id <id>`
+    - Optional: `--column-id`, `--issue-repository`
+    - Takes the issue's card off the project. `--column-id` is the column the
+      card is in, and is found on the board when it is omitted; an issue with no
+      card there is reported as having none.
 
 The project endpoints identify an issue by its global ID, which is not the
 number shown in the web UI: `my-org/my-repo#15` may well be global ID `1854`.
@@ -342,6 +575,39 @@ for you:
   ID. `--issue-repository` also overrides `--repository`, for the case of a
   repository project holding an issue from elsewhere.
 
+`--column-id` does not mean the same thing to all three commands. For `add` and
+`move` it is where the card is going, which only the caller can say. For
+`remove` it is where the card already is, which the board can be asked - so the
+option is optional there, and omitting it has the project's columns walked to
+find the card:
+
+```console
+$ gitea-cli project issue remove --owner my-org --project-id 1 \
+      --issue-repository my-repo --issue-id 42
+```
+
+The column the card was taken off comes back as `metadata.resolved_column_id`,
+and an issue with no card on the project is reported as having none rather than
+removed from a column chosen for it.
+
+A column found that way is read back as well: the board is walked again after
+the removal, and a zero exit status says that no column of the project holds a
+card for the issue afterwards, rather than that a request to take one off was
+accepted. The walk and the removal are separate requests, so a card moved in
+between leaves the removal addressed to a column the card has left, which is a
+removal with nothing to do — and whether the instance refuses that call or
+answers it with a success, the status code is an answer about the request and
+not about the card. It is the whole board that is read back rather than the
+column the removal named, because that column holds no card whether the removal
+took it off or the card had already moved elsewhere. The window is narrowed and
+not closed: Gitea has no conditional delete, so a card put back on the board
+after the confirming walk is one the command has already reported on.
+
+A `--column-id` that is passed is used as it stands, and nothing is read back
+for it: a column that does not hold the card is the caller's call to make rather
+than something quietly corrected here, and whatever the instance answers such a
+removal with is reported as it came.
+
 `add` and `move` are not two ways of doing the same thing. `add` puts an issue
 on a board, giving it a card in a column; `move` relocates the card it already
 has there, and an issue with no card has nothing to relocate. Gitea's move
@@ -422,14 +688,18 @@ gitea-cli repo list --owner alice --owner-type user    # a user's repositories
 Every other command answers a question about the instance now. `watch` answers
 what moved since you last looked: it keeps a local cache of issue snapshots and
 reports the difference between that cache and the instance, then records the
-instance as the new baseline.
+instance as the new baseline. `list` does both in one run; `--no-advance` and
+`advance` pull them apart, for a caller that wants a change to survive until it
+has been acted on rather than until it has been reported.
 
 The family is called `watch` because that is what it is for. `state` names the
 cache rather than the purpose, and `diff` suggests comparing two things you
 name, where this compares the present against whatever was last seen.
 
 - `gitea-cli watch list --owner <owner> [--repository <repo>] [--project-id <id>]`
-    - Optional: `--state-file`, `--dry-run`
+    - Optional: `--state-file`, `--dry-run` (also spelled `--no-advance`)
+- `gitea-cli watch advance --owner <owner> [--repository <repo>] [--project-id <id>]`
+    - Optional: `--state-file`
 
 Each `--repository` watches the open issues of that repository, and each
 `--project-id` watches the cards on that board. Both may be repeated, and both
@@ -492,10 +762,6 @@ Three behaviours of it are worth knowing before it surprises you:
   announcing every comment on every watched issue as rewritten. It is logged,
   and it happens once.
 
-`--dry-run` reports the changes and leaves the cache untouched, so the same
-changes come back on the next run. Everything else about the run is unchanged,
-including the requests it makes.
-
 A cache that cannot be written fails the run: the changes it reported would
 otherwise be reported again forever, which is worth an error rather than a
 silent one-line difference. As with every other failure, nothing is printed on
@@ -539,6 +805,48 @@ what kind of change it was, and what was added and removed:
 `issue_count`, `change_count`, `state_file` and `dry_run`, so a run that
 reported nothing still says why.
 
+#### Detecting a change without consuming it
+
+By default `list` does both at once: it reports the difference and advances the
+cache past it, so a change is announced exactly once whether or not anyone was
+in a position to act on it. A consumer that was busy - its previous run still in
+flight, its queue full - drops the change, and the next run has nothing to say
+about it.
+
+`--dry-run`, also spelled `--no-advance`, reports the changes and leaves the
+cache exactly as it was, so they come back on the next run. Everything else
+about the run is unchanged, including the requests it makes. `watch advance`
+then records the current state as the new baseline, which is how a caller
+commits the cache once it has actually handled what it was told about:
+
+```bash
+changes=$(gitea-cli --output json watch list --owner my-org --repository my-repo --no-advance)
+if handle "$changes"; then
+    gitea-cli watch advance --owner my-org --repository my-repo
+fi
+```
+
+`advance` names its scopes exactly as `list` does, reads the same
+`--state-file`, and reports one line per scope rather than one per change:
+
+```console
+$ gitea-cli watch advance --owner my-org --repository my-repo --project-id 29
+repo:my-org/my-repo: recorded 12 issues, 1 change baselined
+project:my-org/29: recorded 5 issues, unchanged since the cache
+```
+
+In `json` its `data` is one record per scope - `scope`, `issue_count`,
+`change_count` and `baselined` - and its `metadata` carries `scopes`,
+`baselined_scopes`, `issue_count`, `change_count` and `state_file`.
+
+What it commits is the state of the instance **now**, not the state the dry run
+saw: the dry run deliberately wrote nothing down, so there is nothing else left
+to commit. That leaves one window the pair does not close - a change landing
+between the two calls is baselined without ever having been reported.
+`change_count` is how far the baseline moved, so an advance reporting more
+changes than its dry run did is that window showing; keeping the two calls close
+together is what keeps it small.
+
 #### Cost
 
 A run lists every page of each scope, and then every page of the comments of
@@ -546,6 +854,10 @@ every issue in it. That is one request per page of issues plus one per page of
 comments per issue, which is what makes comment edits detectable and what makes
 a large repository worth a longer interval.
 
+`advance` costs exactly what `list` costs: it walks the same pages, and only
+what it does with them differs. Pairing a dry run with an advance therefore
+doubles the requests of the tick it replaces.
+
 ## Examples
 
 List all open issues in a repository:
@@ -565,6 +877,80 @@ gitea-cli issue create \
     --milestone 3
 ```
 
+Start a workflow, then follow the run it started:
+
+```bash
+run=$(gitea-cli --output json actions workflow dispatch \
+    --owner my-org \
+    --repository my-repo \
+    --workflow-id build.yml \
+    --ref main \
+    --input environment=staging \
+    --return-run-details |
+    jq -r '.data.workflow_run_id')
+
+gitea-cli --output json actions run get --owner my-org --repository my-repo --run-id "$run" |
+    jq -r '.data | "\(.status) \(.conclusion // "-")"'
+```
+
+Read the log of the job that failed:
+
+```bash
+gitea-cli --output json actions run jobs \
+    --owner my-org --repository my-repo --run-id 42 |
+    jq -r '.data.jobs[] | select(.conclusion == "failure") | .id' |
+    while read -r job; do
+        gitea-cli actions job logs --owner my-org --repository my-repo --job-id "$job"
+    done
+```
+
+Rerun only the jobs that failed, then wait for the run to settle:
+
+```bash
+gitea-cli actions run rerun \
+    --owner my-org --repository my-repo --run-id 42 --failed-jobs
+
+until [ "$(gitea-cli --output json actions run get \
+    --owner my-org --repository my-repo --run-id 42 |
+    jq -r '.data.status')" != "in_progress" ]; do
+    sleep 10
+done
+```
+
+Set a secret without putting it in the shell history or the process list:
+
+```bash
+read -rs -p 'token: ' token
+printf %s "$token" |
+    gitea-cli actions secret set \
+        --owner my-org --repository my-repo \
+        --secret-name DEPLOY_TOKEN --data - --description 'staging deploys'
+unset token
+```
+
+Find the jobs that are waiting for a runner across a whole organization, and the
+runners that could take them:
+
+```bash
+gitea-cli --output json actions job list --owner my-org --status queued |
+    jq -r '.data.jobs[] | "\(.id)\t\(.name)"'
+
+gitea-cli --output json actions runner list --owner my-org |
+    jq -r '.data.runners[] | "\(.name)\t\(.status)\t\([.labels[].name] | join(","))"'
+```
+
+Download the artifacts of a run, skipping the ones whose archive is gone:
+
+```bash
+gitea-cli --output json actions artifact list \
+    --owner my-org --repository my-repo --run-id 42 |
+    jq -r '.data.artifacts[] | select(.expired == false) | "\(.id)\t\(.name)"' |
+    while IFS=$'\t' read -r id name; do
+        gitea-cli actions artifact download \
+            --owner my-org --repository my-repo --artifact-id "$id" --file "$name.zip"
+    done
+```
+
 Put an issue on a project board, in a column of it, addressing the issue by the
 number shown in the web UI: