integration: read prebuilt-image env knobs via one envknob helper

Replace the repeated os.Getenv(HEADSCALE_INTEGRATION_*_IMAGE) + strings.Cut
parsing in hsic/dsic/scenario with integrationutil.PrebuiltImage (built on
tailscale envknob), and switch the remaining raw reads in tsic/tsric to
envknob.String. One documented place for the prebuilt-image knobs.

Author: kradalby

integration/dsic/dsic.go

@@ -7,7 +7,6 @@ import (
 	"log"
 	"net"
 	"net/http"
-	"os"
 	"strconv"
 	"strings"
 	"time"
@@ -27,12 +26,7 @@ const (
 	dockerExecuteTimeout = 60 * time.Second
 )
 
-var (
-	errDERPerStatusCodeNotOk    = errors.New("DERPer status code not OK")
-	errInvalidDerperImageFormat = errors.New(
-		"invalid HEADSCALE_INTEGRATION_DERPER_IMAGE format, expected repository:tag",
-	)
-)
+var errDERPerStatusCodeNotOk = errors.New("DERPer status code not OK")
 
 // DERPServerInContainer represents DERP Server in Container (DSIC).
 type DERPServerInContainer struct {
@@ -233,13 +227,12 @@ func New(
 	// In CI / nix checks a prebuilt derper image is provided so we neither build
 	// the image nor clone tailscale at runtime, mirroring the tailscale and
 	// headscale image injection. Only the head image is prebuilt.
-	prebuiltImage := os.Getenv("HEADSCALE_INTEGRATION_DERPER_IMAGE")
-	if prebuiltImage != "" && version == "head" {
-		repo, tag, ok := strings.Cut(prebuiltImage, ":")
-		if !ok {
-			return nil, errInvalidDerperImageFormat
-		}
+	repo, tag, prebuilt, err := integrationutil.PrebuiltImage("HEADSCALE_INTEGRATION_DERPER_IMAGE")
+	if err != nil {
+		return nil, err
+	}
 
+	if prebuilt && version == "head" {
 		runOptions.Repository = repo
 		runOptions.Tag = tag
 

integration/hsic/hsic.go

@@ -55,10 +55,8 @@ const (
 )
 
 var (
-	errHeadscaleStatusCodeNotOk    = errors.New("headscale status code not ok")
-	errInvalidHeadscaleImageFormat = errors.New("invalid HEADSCALE_INTEGRATION_HEADSCALE_IMAGE format, expected repository:tag")
-	errHeadscaleImageRequiredInCI  = errors.New("HEADSCALE_INTEGRATION_HEADSCALE_IMAGE must be set in CI")
-	errInvalidPostgresImageFormat  = errors.New("invalid HEADSCALE_INTEGRATION_POSTGRES_IMAGE format, expected repository:tag")
+	errHeadscaleStatusCodeNotOk   = errors.New("headscale status code not ok")
+	errHeadscaleImageRequiredInCI = errors.New("HEADSCALE_INTEGRATION_HEADSCALE_IMAGE must be set in CI")
 )
 
 type fileInContainer struct {
@@ -404,12 +402,12 @@ func New(
 		pgRepo := "postgres"
 		pgTag := "latest"
 
-		if prebuiltImage := os.Getenv("HEADSCALE_INTEGRATION_POSTGRES_IMAGE"); prebuiltImage != "" {
-			repo, tag, found := strings.Cut(prebuiltImage, ":")
-			if !found {
-				return nil, errInvalidPostgresImageFormat
-			}
+		repo, tag, prebuilt, err := integrationutil.PrebuiltImage("HEADSCALE_INTEGRATION_POSTGRES_IMAGE")
+		if err != nil {
+			return nil, err
+		}
 
+		if prebuilt {
 			pgRepo = repo
 			pgTag = tag
 		}
@@ -508,16 +506,13 @@ func New(
 	var container *dockertest.Resource
 
 	// Check if a pre-built image is available via environment variable
-	prebuiltImage := os.Getenv("HEADSCALE_INTEGRATION_HEADSCALE_IMAGE")
-
-	if prebuiltImage != "" {
-		log.Printf("Using pre-built headscale image: %s", prebuiltImage) //nolint:gosec // G706: integration-only log of trusted env value
-		// Parse image into repository and tag
-		repo, tag, ok := strings.Cut(prebuiltImage, ":")
-		if !ok {
-			return nil, errInvalidHeadscaleImageFormat
-		}
+	repo, tag, prebuilt, err := integrationutil.PrebuiltImage("HEADSCALE_INTEGRATION_HEADSCALE_IMAGE")
+	if err != nil {
+		return nil, err
+	}
 
+	if prebuilt {
+		log.Printf("Using pre-built headscale image: %s:%s", repo, tag) //nolint:gosec // G706: integration-only log of trusted env value
 		runOptions.Repository = repo
 		runOptions.Tag = tag
 
@@ -528,7 +523,7 @@ func New(
 			dockertestutil.DockerAllowNetworkAdministration,
 		)
 		if err != nil {
-			return nil, fmt.Errorf("running pre-built headscale container %q: %w", prebuiltImage, err)
+			return nil, fmt.Errorf("running pre-built headscale container %s:%s: %w", repo, tag, err)
 		}
 	} else if util.IsCI() {
 		return nil, errHeadscaleImageRequiredInCI

integration/integrationutil/util.go

@@ -8,20 +8,45 @@ import (
 	"crypto/x509"
 	"crypto/x509/pkix"
 	"encoding/pem"
+	"errors"
 	"fmt"
 	"io"
 	"math/big"
 	"path/filepath"
+	"strings"
 	"time"
 
 	"github.com/juanfont/headscale/hscontrol/types"
 	"github.com/juanfont/headscale/hscontrol/util"
 	"github.com/juanfont/headscale/integration/dockertestutil"
 	"github.com/ory/dockertest/v3"
 	"github.com/ory/dockertest/v3/docker"
+	"tailscale.com/envknob"
 	"tailscale.com/tailcfg"
 )
 
+var errInvalidImageFormat = errors.New("integration image env must be in repository:tag format")
+
+// PrebuiltImage reads a HEADSCALE_INTEGRATION_*_IMAGE knob (the full var name,
+// e.g. "HEADSCALE_INTEGRATION_HEADSCALE_IMAGE") and splits it into repository
+// and tag. The bool is false when the knob is unset — the suite then builds the
+// image itself; it errors when the value is set but is not "repository:tag".
+// This is the one place the prebuilt-image knobs (used by the CI / nix-check
+// path) are read, via tailscale's envknob.
+func PrebuiltImage(envVar string) (string, string, bool, error) {
+	image := envknob.String(envVar)
+	if image == "" {
+		return "", "", false, nil
+	}
+
+	repo, tag, found := strings.Cut(image, ":")
+	if !found {
+		return "", "", false, fmt.Errorf("%s=%q: %w", envVar, image, errInvalidImageFormat)
+	}
+
+	return repo, tag, true, nil
+}
+
 // PeerSyncTimeout returns the timeout for peer synchronization based on environment:
 // 60s for dev, 120s for CI.
 func PeerSyncTimeout() time.Duration {

integration/scenario.go

@@ -1585,21 +1585,19 @@ const (
 
 var errStatusCodeNotOK = errors.New("status code not OK")
 
-var errInvalidHeadscaleImageFormat = errors.New("HEADSCALE_INTEGRATION_HEADSCALE_IMAGE must be in 'repository:tag' format")
-
 // runHeadscaleImageContainer starts runOptions from the prebuilt headscale
 // image when HEADSCALE_INTEGRATION_HEADSCALE_IMAGE is set, otherwise it builds
 // Dockerfile.integration. The mock OIDC provider (headscale mockoidc) and the
 // webservice (python3 -m http.server) both run on the headscale image, so they
 // share the same prebuilt-or-build path hsic uses for headscale itself — which
 // is what lets them come up offline (e.g. in the nix VM checks).
 func (s *Scenario) runHeadscaleImageContainer(runOptions *dockertest.RunOptions) (*dockertest.Resource, error) {
-	if prebuiltImage := os.Getenv("HEADSCALE_INTEGRATION_HEADSCALE_IMAGE"); prebuiltImage != "" {
-		repo, tag, ok := strings.Cut(prebuiltImage, ":")
-		if !ok {
-			return nil, errInvalidHeadscaleImageFormat
-		}
+	repo, tag, prebuilt, err := integrationutil.PrebuiltImage("HEADSCALE_INTEGRATION_HEADSCALE_IMAGE")
+	if err != nil {
+		return nil, err
+	}
 
+	if prebuilt {
 		runOptions.Repository = repo
 		runOptions.Tag = tag
 

integration/tsic/tsic.go

@@ -26,6 +26,7 @@ import (
 	"github.com/juanfont/headscale/integration/integrationutil"
 	"github.com/ory/dockertest/v3"
 	"github.com/ory/dockertest/v3/docker"
+	"tailscale.com/envknob"
 	"tailscale.com/ipn"
 	"tailscale.com/ipn/ipnstate"
 	"tailscale.com/ipn/store/mem"
@@ -432,7 +433,7 @@ func New(
 	switch version {
 	case VersionHead:
 		// Check if a pre-built image is available via environment variable
-		prebuiltImage := os.Getenv("HEADSCALE_INTEGRATION_TAILSCALE_IMAGE")
+		prebuiltImage := envknob.String("HEADSCALE_INTEGRATION_TAILSCALE_IMAGE")
 
 		// If custom build tags are required (e.g., for websocket DERP), the
 		// default pre-built image won't have the necessary code compiled in. A
@@ -441,7 +442,7 @@ func New(
 		// building the image with the tags.
 		hasBuildTags := len(tsic.buildConfig.tags) > 0
 		if hasBuildTags && prebuiltImage != "" {
-			wsImage := os.Getenv("HEADSCALE_INTEGRATION_TAILSCALE_WEBSOCKET_IMAGE")
+			wsImage := envknob.String("HEADSCALE_INTEGRATION_TAILSCALE_WEBSOCKET_IMAGE")
 			if tsic.withWebsocketDERP && wsImage != "" {
 				prebuiltImage = wsImage
 			} else {

integration/tsric/tsric.go

@@ -12,13 +12,13 @@ import (
 	"fmt"
 	"io"
 	"log"
-	"os"
 	"strings"
 
 	"github.com/juanfont/headscale/integration/dockertestutil"
 	"github.com/juanfont/headscale/integration/integrationutil"
 	"github.com/ory/dockertest/v3"
 	"github.com/ory/dockertest/v3/docker"
+	"tailscale.com/envknob"
 	"tailscale.com/util/rands"
 )
 
@@ -35,7 +35,7 @@ const (
 
 // getPrebuiltImage returns the pre-built tailscale-rs Docker image name if set.
 func getPrebuiltImage() string {
-	return os.Getenv("HEADSCALE_INTEGRATION_TAILSCALE_RS_IMAGE")
+	return envknob.String("HEADSCALE_INTEGRATION_TAILSCALE_RS_IMAGE")
 }
 
 // TailscaleRustInContainer runs the tailscale-rs axum example as an