From 7b569cae30d51321cd9fe6bb1a9c655566bb66d1 Mon Sep 17 00:00:00 2001 From: Samuel K Date: Thu, 30 Jul 2026 22:07:13 -0500 Subject: [PATCH] docs(contributing): document testing agent changes against a remote provider Testing changes to pkg/agent/pkg/git against a local docker provider just works, since the CLI process is the agent. Against a remote/SSH provider, the agent is a separate binary injected onto that host, and two things bit us debugging the git-lfs install fix: dev builds skip the remote version check (so a stale cached binary silently gets reused instead of a freshly built one), and DEVSY_AGENT_BINARY has to match the remote's OS/arch, not the local machine's. Adds a cli:test:remote task that builds dev binaries for every OS/arch, clears the remote's cached agent binary, and runs `up --reset` with DEVSY_AGENT_BINARY pointed at the right one. --- CONTRIBUTING.md | 30 ++++++++++++++++++++++++++++++ Taskfile.yml | 22 ++++++++++++++++++++++ 2 files changed, 52 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6c8d12118..1d6c92659 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -180,6 +180,35 @@ This requires: ./dist/devsy-dev_linux_amd64_v1/devsy-linux-amd64 up examples/simple ``` +### Testing Agent Changes Against a Remote/SSH Provider + +The Quick Start above works because with a local `docker` provider, the CLI +process you just built *is* the agent. For any remote/SSH/cloud provider, the +agent runs as a separate binary injected onto that host, so testing a change +to agent code (`pkg/agent`, `pkg/git`, etc.) needs a couple of extra steps. + +1. Build dev binaries for every OS/arch (`task cli:build:dev` builds all of + them in one pass: `dist/devsy-dev__*/devsy--`). +2. Set `DEVSY_AGENT_BINARY` to the binary matching your **remote host's** + OS/arch (not your own machine's) before running `up`/`ssh`/etc. Check + `devsy workspace list` for the provider's `HOST`/target arch if unsure. +3. If you've tested against that workspace before, the remote host likely + already has an agent binary cached at the provider's `AGENT_PATH`. A dev + build (`version == v0.0.0`) skips the remote version check and only + verifies *that a binary exists* there — so a stale cached binary is + silently reused instead of your new one. Delete it first to force a fresh + injection: `ssh rm -f ` (both values are in + `devsy workspace list`'s provider options). + +```bash +task cli:build:dev +ssh rm -f +DEVSY_AGENT_BINARY=./dist/devsy-dev_linux_arm64_v8.0/devsy-linux-arm64 \ + ./dist/devsy-dev_linux_amd64_v1/devsy-linux-amd64 workspace up --reset +``` + +`task cli:test:remote` automates this (see below). + ### Using Act for Local CI Testing ```bash @@ -265,6 +294,7 @@ task cli:build # Build CLI for production task cli:build:dev # Build CLI for development task cli:lint # Run linters task cli:test # Run unit tests +task cli:test:remote # Test agent changes against a remote/SSH provider workspace task cli:tidy # Tidy go.mod and go.sum # Desktop tasks diff --git a/Taskfile.yml b/Taskfile.yml index b9363951a..0f73bdb4c 100644 --- a/Taskfile.yml +++ b/Taskfile.yml @@ -88,6 +88,28 @@ tasks: desc: run devsy unit tests cmd: go test $(go list ./... | grep -v -e /test -e /e2e) -race -coverprofile=dist/profile.out -covermode=atomic + cli:test:remote: + # usage: HOST=user@host AGENT_PATH=/tmp/user/devsy/agent task cli:test:remote -- [extra up flags] + # HOST/AGENT_PATH come from `devsy workspace list`'s provider options. + # GOOS/GOARCH target the remote host (default linux/arm64); override for e.g. an amd64 cloud VM. + desc: build a dev binary and inject it into a remote/SSH-provider workspace, bypassing the stale cached-binary reuse + vars: + GOOS: '{{.GOOS | default "linux"}}' + GOARCH: '{{.GOARCH | default "arm64"}}' + preconditions: + - sh: '[ -n "{{.HOST}}" ]' + msg: "HOST is required, e.g. HOST=user@host task cli:test:remote -- my-workspace" + - sh: '[ -n "{{.AGENT_PATH}}" ]' + msg: "AGENT_PATH is required (see `devsy workspace list`), e.g. AGENT_PATH=/tmp/user/devsy/agent" + cmds: + - task: cli:build:dev + - ssh {{.HOST}} rm -f {{.AGENT_PATH}} + - | + set -e + remote_bin="$(find dist -maxdepth 1 -type d -name 'devsy-dev_{{.GOOS}}_{{.GOARCH}}*')/devsy-{{.GOOS}}-{{.GOARCH}}" + local_bin="$(find dist -maxdepth 1 -type d -name "devsy-dev_$(go env GOOS)_$(go env GOARCH)*")/devsy-$(go env GOOS)-$(go env GOARCH)" + DEVSY_AGENT_BINARY="$remote_bin" "$local_bin" workspace up {{.CLI_ARGS}} --reset + cli:test:e2e:build: desc: build devsy for e2e tests status: