From 262bd53e270b8aca2ec8d637f0d5ef3acdd8ac4b Mon Sep 17 00:00:00 2001 From: Samuel K Date: Mon, 19 Oct 2026 16:16:48 -0600 Subject: [PATCH 1/2] docs(providers): fix binaries example and archive checksum docs Remove archivePath from the direct-binary example; it made Devsy try to extract a non-archive URL. Add a separate tar.gz archive example. Document that the checksum is the SHA256 of the extracted executable (the archive itself is never hashed) and that checksum is optional. --- .../docs/developing-providers/binaries.mdx | 23 +++++++++++++++++-- 1 file changed, 21 insertions(+), 2 deletions(-) diff --git a/sites/docs-devsy-sh/content/docs/developing-providers/binaries.mdx b/sites/docs-devsy-sh/content/docs/developing-providers/binaries.mdx index b6cefee3a0..244d6b20aa 100644 --- a/sites/docs-devsy-sh/content/docs/developing-providers/binaries.mdx +++ b/sites/docs-devsy-sh/content/docs/developing-providers/binaries.mdx @@ -14,7 +14,6 @@ binaries: arch: amd64 path: https://example.com/my-binary-linux-amd64 # URL or local path checksum: - archivePath: bin/my-binary # only if path is an archive name: my-binary # optional, defaults to the file name - os: darwin arch: arm64 @@ -22,7 +21,7 @@ binaries: checksum: ``` -Supported archives are `.tgz`, `.tar`, `.tar.gz` and `.zip`. When a user adds the provider, Devsy picks the item that matches their OS and architecture, downloads it and verifies the checksum. +Supported archives are `.tgz`, `.tar`, `.tar.gz` and `.zip`. When a user adds the provider, Devsy picks the item that matches their OS and architecture, downloads it and, if `checksum` is set, verifies it. See the official providers, such as [devsy-provider-aws](https://github.com/devsy-org/devsy-provider-aws), for complete examples. @@ -30,6 +29,26 @@ See the official providers, such as [devsy-provider-aws](https://github.com/devs Not every provider needs `binaries`. Built-in providers that wrap a CLI the user already has, such as `docker`, expose an option like `DOCKER_PATH` instead of downloading one. +## Archives + +Set `archivePath` only when `path` is an archive. Devsy picks the extraction format from the `path` extension, not from `archivePath`. Setting `archivePath` on a direct binary URL makes Devsy try to extract the binary and fails with `unrecognized archive format`. + +```yaml +binaries: + MY_BINARY: + - os: linux + arch: amd64 + path: https://example.com/my-binary-linux-amd64.tar.gz + archivePath: bin/my-binary # executable inside the archive + checksum: +``` + +Devsy extracts the whole archive into a folder for the binary and keeps its layout, then uses the file at `archivePath`. `name` has no effect on archives. + +## Checksum + +`checksum` is optional. When set, Devsy computes the SHA256 of the executable it will run, after extraction, and compares it case-insensitively. For a direct download this is the downloaded file. For an archive it is the extracted file at `archivePath`; the archive itself is never hashed. A mismatch deletes the file and fails the download without retrying. + ## Use a binary Devsy exposes each binary's path as an environment variable with the same name. From 8fe8ddc1c5c5e0ae0a46f7639fbfc35a395d3ba4 Mon Sep 17 00:00:00 2001 From: Samuel K Date: Mon, 19 Oct 2026 20:21:32 -0600 Subject: [PATCH 2/2] docs(providers): scope archive and checksum rules to code behavior --- .../content/docs/developing-providers/binaries.mdx | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/sites/docs-devsy-sh/content/docs/developing-providers/binaries.mdx b/sites/docs-devsy-sh/content/docs/developing-providers/binaries.mdx index 244d6b20aa..57b2e178c6 100644 --- a/sites/docs-devsy-sh/content/docs/developing-providers/binaries.mdx +++ b/sites/docs-devsy-sh/content/docs/developing-providers/binaries.mdx @@ -31,7 +31,7 @@ Not every provider needs `binaries`. Built-in providers that wrap a CLI the user ## Archives -Set `archivePath` only when `path` is an archive. Devsy picks the extraction format from the `path` extension, not from `archivePath`. Setting `archivePath` on a direct binary URL makes Devsy try to extract the binary and fails with `unrecognized archive format`. +Archive extraction applies only when `path` is an `http://` or `https://` URL. Devsy picks the extraction format from the `path` extension, not from `archivePath`. Devsy requires `archivePath` when `path` is an archive. Setting `archivePath` on a direct binary URL makes Devsy try to extract the binary and fails with `unrecognized archive format`. ```yaml binaries: @@ -43,11 +43,13 @@ binaries: checksum: ``` -Devsy extracts the whole archive into a folder for the binary and keeps its layout, then uses the file at `archivePath`. `name` has no effect on archives. +Devsy extracts the whole archive into a folder for the binary and keeps its layout, then uses the file at `archivePath`. For HTTP(S) archives, `name` is ignored. ## Checksum -`checksum` is optional. When set, Devsy computes the SHA256 of the executable it will run, after extraction, and compares it case-insensitively. For a direct download this is the downloaded file. For an archive it is the extracted file at `archivePath`; the archive itself is never hashed. A mismatch deletes the file and fails the download without retrying. +`checksum` is optional, except for the `agent.binaries` entry selected by `agent.external.binary`, which needs one for every platform. See [External Driver](./driver.mdx#external-driver). + +When set, Devsy computes the SHA256 of the file it will run and compares it case-insensitively. For an HTTP(S) archive that file is the extracted file at `archivePath`; the archive itself is never hashed. A mismatch deletes the file and fails the download without retrying. ## Use a binary