enhance: add builtin:download-artifact (#1344)

Co-authored-by: bircni <[email protected]>

docs/builtin-actions.md

@@ -5,6 +5,7 @@ Built-in actions ship with the runner, so a job needs no action download and no
 ```yaml
 - uses: builtin:checkout
 - uses: builtin:upload-artifact
+- uses: builtin:download-artifact
 ```
 
 ## checkout
@@ -58,4 +59,27 @@ Patterns, symlinks and the artifact's root directory follow `actions/upload-arti
 
 Container jobs list the search paths in the job container and transfer only the selected files, gzipped when the image has gzip, requiring `sh`, `find` and `tar` in the image. On Kubernetes these files still pass through the API server, unlike `actions/upload-artifact`, which uploads from the pod.
 
-With `gitea-runner exec`, it uses the local artifact server of `--artifact-server-path`.
+## download-artifact
+
+Works like `actions/download-artifact` v8 with these inputs. Any other input logs a warning, as on GitHub.
+
+| Input | Default |
+| --- | --- |
+| `name` | empty, every artifact of the run |
+| `artifact-ids` | empty, comma-separated IDs instead of `name` |
+| `path` | workspace root, `~` is the job user's home |
+| `pattern` | empty, a glob the artifact names must match, without the extglobs and brace ranges of minimatch, ignored with `name` or `artifact-ids` |
+| `merge-multiple` | `false`, several artifacts go to `path/<name>`, `true` puts them all in `path` |
+| `github-token` | empty, a token to download from another run or repository |
+| `repository` | `github.repository`, with `github-token` |
+| `run-id` | `github.run_id`, with `github-token` |
+| `skip-decompress` | `false`, `true` keeps a zipped artifact as `<name>.zip` |
+| `digest-mismatch` | `error`, also `ignore`, `info` or `warn` |
+
+ZIP entries become regular files with current modification times, so files lose their executable bit and symlinks become files containing their targets. `digest-mismatch` only applies when the server reports a digest, which Gitea does not. The step outputs `download-path`.
+
+The runner downloads each artifact to a temporary file on the runner because the zip is read out of order, then streams the files into the job container. On Kubernetes, the stream goes through the API server, gzipped when the image has gzip, or over the pod network with `kubernetes.transfer.mode` set to `auto` or `direct`, while `actions/download-artifact` downloads from the pod directly.
+
+`github-token` needs Gitea 1.24 or later and is only sent to the instance the runner is registered with. Downloads from another run paginate through its artifacts and skip expired ones, where `actions/download-artifact` sees only Gitea's first 30 and fails on an expired newest copy. `run-id` must be positive, since Gitea treats nonpositive IDs as a request for artifacts from every run. Artifact names and ZIP entries that would leave the destination are rejected.
+
+With `gitea-runner exec`, both actions use the local artifact server of `--artifact-server-path`, which serves no other runs for `github-token`.