klinux / klinux/gocdnext

feat(agent): Windows + macOS agents — host/shell executor + OS-aware scheduling

Open
#69 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

enhancement
Dominant language
Go
Stars
7
Forks
3
Avg merge
2h 12m
Merged PRs (30d)
30

Description

Goal

Support Windows and macOS agents (like Woodpecker's local backend), so jobs can target those platforms (Xcode/iOS on mac, .NET/MSVC on Windows). This issue captures the architecture assessment for later validation + scoping — not committing to an implementation yet.

Where we are today

We already have the two bones Woodpecker uses (host executor + platform routing), but both are incomplete:

  • The Shell engine is the host executor — but it's Linux/Unix-only: sh -c (agent/internal/engine/shell.go:85) and Unix process-group kill (syscall.SysProcAttr{Setpgid} + syscall.Kill(-pid, SIGKILL), shell.go:93-104).
  • The agent already advertises os/arch at registration (agent/internal/rpc/client.go:263-264, RegisterRequest.os/arch) — but the scheduler ignores it: SessionStore keeps only tags/capacity/engine and FindIdleWithTags matches tags only (server/internal/grpcsrv/sessions.go). No job/profile carries an OS selector.
  • Plugins are 100% OCI Linux images (plugins/, ~58 Dockerfiles); the Shell engine explicitly rejects plugin tasks (shell.go:72-81).
  • The agent is built/shipped Linux-only (agent/Dockerfile Alpine; release.yml image matrix; no GOOS/GOARCH cross-compile).

Three distances

  1. macOS shell agent — CLOSE. The Shell engine is POSIX, so it already runs on macOS; the agent is pure Go (CGO_ENABLED=0) → cross-compiles to darwin/* trivially. Missing: OS/arch routing in the scheduler, a darwin binary in CI, and an os.TempDir() workspace default. Caveat: shell steps only — no container plugins on bare macOS (which matches how mac CI agents are used).
  2. Windows shell agent — MEDIUM. Same routing + packaging, plus a Windows backend for the Shell engine: cmd.exe/PowerShell instead of sh -c, and a Windows process-tree kill (the current syscall.Kill(-pid,…) won't even compile on Windows). Isolated platform module.
  3. Full plugin parity — FAR / likely out of scope. Would need Windows-container variants of every plugin (huge maintenance); bare macOS can't run containers at all. Pragmatic target is shell-step agents.

Proposed smallest-first path

  1. Scheduler routes by os/arch — store them on the session (data already arrives) and AND-match them alongside tags; add an os:/platform: selector to the job spec or runner profile (reuses the v0.14.0 runner-profile scheduling / node_selector machinery). Server-only; no agent change — and this alone makes a macOS agent usable since its Shell engine already runs.
  2. Cross-compile + publish darwin/arm64 (+ windows/amd64) agent binaries.
  3. macOS agent ships on 1+2 (shell-only; document the no-plugins caveat).
  4. Windows backend for the Shell engine (cmd/PowerShell + Job-Object process kill).
  5. (Punt) Windows/macOS plugin images.

Open questions for validation

  • Distribution: standalone binary + service install, or also a container path?
  • Routing UX: OS as a first-class platform: on the job, vs. just conventional tags (os:windows)?
  • Do we want a local/shell agent posture documented as first-class (security implications: host execution, no container isolation)?

Assessment done during the v0.49.0 cycle. No code yet — for discussion.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reading agent/internal/engine/shell.go, agent/internal/rpc/client.go, and server/internal/grpcsrv/sessions.go, then inspect release.yml and the runner-profile scheduling machinery. The work is ready for implementation only after the routing UX, distribution model, local-agent posture, and shell-only plugin scope are decided; completion would cover the agreed platform-routing and packaging steps with the stated Windows backend or explicit scope boundary.

Written by the indexing model from the issue text.

Assessment

Tech stack
docker, go, powershell, shell
Domain
backend, ci-cd, devops, distributed-systems
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Needs clarification
Newbie friendliness
30/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.