Repository navigation
Convert golang-api to a Go AppHost - #2111
Closed
David Pine (IEvangelist) wants to merge 2 commits into
Closed
David Pine (IEvangelist) wants to merge 2 commits into
David Pine (IEvangelist) wants to merge 2 commits into
Conversation
Replace the TypeScript AppHost with a Go AppHost that uses AddGoApp and AddDockerComposeEnvironment. AddGoApp runs `go run .` during `aspire run` and builds the image from the Dockerfile that is checked in next to the API when publishing, so the API source is unchanged. Pin the Aspire 17.0.0 SDK and packages, document the 17.0 CLI and Go 1.26 prerequisites, and correct the teardown step name to docker-compose-down-env. Add `*.go text eol=lf` so gofmt accepts Go files on every platform, and mark the sample as a Go AppHost in the root README. Closes #2110 Part of microsoft/aspire#21115 Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: c8717a87-0ee5-4296-a6fd-ea6e2d91a57e
The Aspire 13.6.0 CLI that the build job installs is too old for Go AppHosts, and Build.proj only enumerates C# and TypeScript AppHosts, so Go AppHosts were not covered. Add a Linux job that installs the 17.0.0 CLI from a dedicated version variable, sets up Go with a SHA-pinned actions/setup-go, and runs build/validate-go.sh. The script restores each samples/**/apphost.go and runs go build and go vet on it, and fails when no Go AppHost is found. Add the job to ci-gate. Part of microsoft/aspire#21115 Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: c8717a87-0ee5-4296-a6fd-ea6e2d91a57e
Contributor
There was a problem hiding this comment.
🔵 Needs a closer look
Human confirmation is needed that the upstream prerequisites and public Aspire 17.0 artifacts are available, the new action is allowed, and validation passes against the committed pins.
No open issues 🎉
1 file not reviewed
samples/golang-api/package-lock.json: Generated file
What changed in this PR
Converts the Go API sample from a TypeScript AppHost to a native Go AppHost and adds dedicated repository CI validation for Go AppHosts.
Changes:
- Replaces TypeScript tooling with Go orchestration while retaining local API execution and Dockerfile-based publishing.
- Adds restore, build, and vet validation to the required CI gate.
- Documents the sample’s separate Aspire 17.0 prerequisites and updates deployment guidance.
| File | Description |
|---|---|
| samples/golang-api/tsconfig.apphost.json | Removes obsolete TypeScript compiler configuration. |
| samples/golang-api/README.md | Documents Go orchestration, prerequisites, and teardown. |
| samples/golang-api/package.json | Removes Node-based AppHost dependencies and scripts. |
| samples/golang-api/package-lock.json | Removes the obsolete npm lockfile. |
| samples/golang-api/go.mod | Defines the AppHost module and generated SDK reference. |
| samples/golang-api/eslint.config.mjs | Removes obsolete TypeScript lint configuration. |
| samples/golang-api/aspire.config.json | Selects Go and pins Aspire packages to 17.0.0. |
| samples/golang-api/apphost.mts | Removes the previous TypeScript AppHost. |
| samples/golang-api/apphost.go | Adds Go API orchestration and resource error handling. |
| README.md | Updates the sample listing and CLI version guidance. |
| build/validate-go.sh | Discovers, restores, builds, and vets Go AppHosts. |
| .github/workflows/ci.yml | Adds Go validation and requires it in CI Gate. |
| .gitattributes | Enforces LF line endings for Go sources. |
Review effort: Balanced
This was referenced Oct 28, 2026
8 tasks
Member
Author
|
Closing in favor of #2173, which now includes this change (the Go AppHost conversion and the |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Important
Depends on microsoft/aspire#21183 and the Aspire 17.0 release. Ready for review, but do not merge before the 17.0.0 CLI and packages are public.
Aspire.Hosting.GoandAspire.Hosting.Dockerpackages must be published, or the newgo-apphostsjob and every restore of this sample fail.apphost.goidioms,go.modandaspire.config.jsonshape).Summary
Converts
samples/golang-apifrom a TypeScript AppHost to a Go AppHost and adds a CI job that restores, builds and vets every Go AppHost in the repository.Closes #2110
Part of microsoft/aspire#21115
The pins stay at
17.0.0(no prerelease or unpinned downloads), so the newgo-apphostsjob is expected to fail until the 17.0.0 CLI and packages are published. Re-run CI once they ship.What changed
Sample (
samples/golang-api)apphost.go(new):AddDockerComposeEnvironment("env")plusAddGoApp("api", "./api")withWithModTidy(),WithHttpEndpoint(injectsPORT),WithHttpHealthCheckon/healthandWithExternalHttpEndpoints().AddGoApprunsgo run .locally. When publishing, it builds the API container from the checked-inapi/Dockerfile(its Dockerfile generation is skipped whenapi/Dockerfileexists), so the image is built the same way as before.go.mod(new) andaspire.config.json:appHost.pathisapphost.go,languageisgo, andsdk.version,Aspire.Hosting.DockerandAspire.Hosting.Goare pinned to17.0.0. Profiles and ports are unchanged.apphost.mts,package.json,package-lock.json,tsconfig.apphost.jsonandeslint.config.mjs.api/is untouched.README.md: describes the Go AppHost, adds a Prerequisites section (Aspire CLI 17.0+, Go 1.26+, a container runtime), shows the Go snippet with an explanation of run vs publish, and fixes the teardown step name fromdocker-compose-down-dctodocker-compose-down-env(step names follow the environment name; confirmed withaspire do --list-steps).Repository
README.md: the Go API row reads "Go AppHost", and the "Aspire version" section says this sample needs the 17.0.0 CLI and SDK (the others use 13.6.0), how to install it, and which CI job uses which pin..gitattributes:*.go text eol=lf. gofmt flags CRLF files, which an autocrlf checkout on Windows would otherwise produce..github/workflows/ci.ymlandbuild/validate-go.sh(new): ago-apphostsjob.build/Build.projonly enumeratesapphost.cs,*.AppHost.csprojandapphost.mts, so Go AppHosts need their own job.ubuntu-24.04, 15 minute timeout, inherits the workflow-levelpermissions: contents: read; checkout usespersist-credentials: false.actions/setup-gois pinned to a full SHA withcache: false(there is no rootgo.sumto key a cache on).GO_APPHOST_ASPIRE_CLI_VERSION(17.0.0), so the other samples keep their own CLI pin.validate-go.shrunsaspire restore --apphost .,go build -o /dev/null ./...andgo vet ./...in every directory that has a trackedsamples/**/apphost.go.-o /dev/nullkeepsgo buildfrom leaving anapphostbinary in the sample directory. It fails when no Go AppHost is found, so moving or renaming the AppHost cannot turn the job into a silent pass.ci-gatealso needsgo-apphosts..gitignore: the Go starter's is only.aspire/, which the root.gitignorealready covers.Validation
All checks ran in a scratch copy of
samples/golang-apioutside the repository, with17.0.0-devpins, a locally built dev Aspire CLI (17.0.0-dev,features__experimentalPolyglotGo=true), Go 1.27.0 and Docker 29.9.1. In the scratch copyapphost.go,go.modandapi/are byte-identical to the committed files, andaspire.config.jsondiffers only in the version pins. The released 17.0.0 CLI and packages do not exist yet, so nothing could run against the committed pins.aspire new aspire-go-starter --version 17.0.0-dev(scaffold comparison)apphost.goidioms,go.modshape andaspire.config.jsonshape match the starter. The only difference is the starter's redundantWithOtlpExporter(), whichAddGoAppalready adds.aspire restore --apphost . --non-interactive --nologo.aspire/modulesand resolvedAspire.Hosting.DockerandAspire.Hosting.Go.go build -o /dev/null ./...,go vet ./...,gofmt -l apphost.goaspire run, thenaspire wait api --status healthyapihealthy after 9.0s.GET /healthon theapiendpoint{"status":"healthy"}.aspire stop --apphost <path> --pid <pid>aspire publish --apphost . -o <dir> --non-interactive --nologodocker-compose.yamland.env.apihasimage: "${API_IMAGE}"(nobuild:),PORT: "8000"and theOTEL_*variables.docker compose configon the published outputservice "api" has neither an image nor a build context specified. Exit 0 onceAPI_IMAGE=api:checkis set (see Notes).aspire do --apphost . --list-stepsbuild-api,push-api,docker-compose-up-envanddocker-compose-down-env.aspire do build-api --apphost . --non-interactive --nologoapi/Dockerfile(User=app,HOST=0.0.0.0,Cmd ["./main"]).docker run -d -p 127.0.0.1::8000 -e PORT=8000 <image>, thenGET /healthStarting server on 0.0.0.0:8000; 200{"status":"healthy"}. Container and image removed afterwards.bash -n build/validate-go.sh(WSL Ubuntu)build/validate-go.shwith stubaspireandgoin a throwaway git repo (WSL Ubuntu)samples/**/apphost.go(ignoresapi/main.goandapphost.mts), printsValidated N Go AppHosts., and on failure emits::error file=<apphost>::and exits with the failing command's exit code without running later samples. With noapphost.goit exits 1 with::error::No Go AppHosts found under samples/.go build -o NUL ./...in a throwaway two-package moduleNULis the Windows spelling of the null device, because/dev/nulldoes not exist there).ci.ymlbuild,go-apphostsandci-gate; top-levelpermissionsiscontents: read;ci-gateneedsbuildandgo-apphosts; all 9uses:references are full-SHA pinned.git diff --check, non-ASCII scan, line-ending checkConfigureDashboard(... WithHostPort(9003))go build,go vetandgofmt -lpass, but the AppHost panics at startup (see Notes).Notes
actions/setup-goneeds allow-listing. New pin:actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0, the latest release (published 2026-07-16). The same SHA is pinned by microsoft/TypeScript, microsoft/sql-server-samples, microsoft/azurelinux and microsoft/onnxruntime. This repository did not usesetup-gobefore, so an admin must add the SHA to the allowed-actions list before the job can run.actions/checkoutreuses the existing pin.Dashboard host port 9003 is not pinned yet (product bug). The TypeScript AppHost used
configureDashboard(d => d.withHostPort({port: 9003})). The Go equivalent compiles, but the AppHost panics with a nil pointer dereference at startup, for bothrunandpublish: theConfigureDashboardcallback receives a nil argument. The host sends the argument with the type idAspire.Hosting/Aspire.Hosting.ApplicationModel.IResourceBuilder1[[Aspire.Hosting.Docker.DockerComposeAspireDashboardResource, ...]], but the Go SDK registers its wrapper only underAspire.Hosting.Docker/Aspire.Hosting.Docker.DockerComposeAspireDashboardResource.wrapIfHandle(transport.go) therefore returns an unwrapped handle andcallbackArg(base.go) decodes it to nil. It likely affects every Go callback whose C# parameter isAction<IResourceBuilder>, and user code cannot work around it. This PR leaves the call out, so the published dashboard port is ephemeral (ports: - "18888"). Once the product bug is fixed, replace the first line of theenvdeclaration inapphost.gowith the following, which compiles and is gofmt-clean. The published port should then be"9003:18888"(expected from readingDockerComposeServiceResource.AddPorts`, not observed). Tracked in Go AppHost: callbacks that take a resource builder receive nil and panic aspire#21255.WithModTidy()hides download failures. In run mode it executesgo mod tidy -e. The-eflag makes tidy exit 0 even when a module cannot be downloaded; it then strips the chirequirefromapi/go.modand emptiesgo.sum, leaving the tree dirty, andgo run .fails with "no required module provides package". The committedapi/go.modandgo.sumare complete, so nothing changes with a working network or module cache. I hit this locally when thegoprocesses launched by the AppHost failed withx509: certificate signed by unknown authoritywhile fetching chi fromproxy.golang.org, although the same download worked from a normal shell. The cause was not identified. Pre-caching withgo mod download github.com/go-chi/chi/v5@v5.2.5avoided it.Published compose output needs an image name.
.envcontains an emptyAPI_IMAGE=, sodocker compose configon the rawaspire publishoutput fails until an image is supplied. The deploy flow is expected to supply it after building and pushing the image; that path was not run (see below).Not run or unverified:
aspire deploy,docker compose upanddocker compose downend to end. Only the API image was built and run on its own.go-apphostsjob on a real runner with the released CLI. The job installs no .NET SDK and relies on the SDK that ships with theubuntu-24.04runner image; whether the released CLI bundle works with it is unverified.aspire runwas verified throughaspire waitand/healthonly.