Add GitOps name_template under controls

Relates to #48625

Lets GitOps own the host name template via controls.name_template in
team YAML. Parsed into GitOpsControls (with type validation and Set()
presence check), applied declaratively through the same team-spec path
as the endpoint (absent key clears the template), and rejected for
org-level and no-team controls. generate-gitops emits controls
field-by-field and does not include name_template, so it does not
round-trip (matches the story's 'No changes' for generation).

Author: juan-fdz-hawa

cmd/fleetctl/fleetctl/generate_gitops.go

@@ -1406,6 +1406,10 @@ func (cmd *GenerateGitopsCommand) generateControls(teamId *uint, teamName string
 			result[jsonFieldName(mdmT, "EnableDiskEncryption")] = teamMdm.EnableDiskEncryption
 			result[jsonFieldName(mdmT, "EnableRecoveryLockPassword")] = teamMdm.EnableRecoveryLockPassword
 			result[jsonFieldName(mdmT, "RequireBitLockerPIN")] = teamMdm.RequireBitLockerPIN
+			// name_template is fleets-only, so only emit it for real fleets.
+			if teamId != nil && *teamId != 0 {
+				result[jsonFieldName(mdmT, "HostNameTemplate")] = teamMdm.HostNameTemplate
+			}
 			result[jsonFieldName(mdmT, "MacOSUpdates")] = teamMdm.MacOSUpdates
 			result[jsonFieldName(mdmT, "IOSUpdates")] = teamMdm.IOSUpdates
 			result[jsonFieldName(mdmT, "IPadOSUpdates")] = teamMdm.IPadOSUpdates

cmd/fleetctl/fleetctl/gitops_test.go

@@ -7218,6 +7218,259 @@ software:
 	})
 }
 
+func TestGitOpsHostNameTemplate(t *testing.T) {
+	// Cannot t.Parallel() — RunServerWithMockedDS sets environment variables.
+	license := &fleet.LicenseInfo{Tier: fleet.TierPremium, Expiration: time.Now().Add(24 * time.Hour)}
+	opts := &service.TestServerOpts{
+		License:       license,
+		KeyValueStore: testing_utils.NewMemKeyValueStore(),
+	}
+	_, ds := testing_utils.RunServerWithMockedDS(t, opts)
+	setupEmptyGitOpsMocks(ds)
+
+	// Mock Apple GDMF API (required for validating OS update minimum version settings)
+	mdmtest.StartNewAppleGDMFTestServer(t)
+
+	const (
+		localTeamName  = "Team1"
+		fleetServerURL = "https://fleet.example.com"
+		orgName        = "GitOps Test"
+		template       = "iPad $FLEET_VAR_HOST_HARDWARE_SERIAL"
+	)
+
+	var savedTeam *fleet.Team
+	ds.TeamByNameFunc = func(ctx context.Context, name string) (*fleet.Team, error) {
+		if name == localTeamName && savedTeam != nil {
+			return savedTeam, nil
+		}
+		return nil, &notFoundError{}
+	}
+	ds.SaveTeamFunc = func(ctx context.Context, tm *fleet.Team) (*fleet.Team, error) {
+		savedTeam = tm
+		return tm, nil
+	}
+	ds.NewTeamFunc = func(ctx context.Context, newTeam *fleet.Team) (*fleet.Team, error) {
+		newTeam.ID = 1
+		savedTeam = newTeam
+		return newTeam, nil
+	}
+	ds.TeamByFilenameFunc = func(ctx context.Context, filename string) (*fleet.Team, error) {
+		if savedTeam != nil && savedTeam.Filename != nil && *savedTeam.Filename == filename {
+			return savedTeam, nil
+		}
+		return nil, &notFoundError{}
+	}
+	defaultTeamConfig := &fleet.TeamConfig{}
+	ds.TeamLiteFunc = func(ctx context.Context, tid uint) (*fleet.TeamLite, error) {
+		if tid == 0 {
+			return &fleet.TeamLite{ID: 0, Name: fleet.ReservedNameNoTeam, Config: defaultTeamConfig.ToLite()}, nil
+		}
+		if tid == 1 && savedTeam != nil {
+			return savedTeam.ToTeamLite(), nil
+		}
+		return nil, nil
+	}
+	ds.DefaultTeamConfigFunc = func(ctx context.Context) (*fleet.TeamConfig, error) { return defaultTeamConfig, nil }
+	ds.SaveDefaultTeamConfigFunc = func(ctx context.Context, config *fleet.TeamConfig) error {
+		defaultTeamConfig = config
+		return nil
+	}
+	ds.LabelIDsByNameFunc = func(ctx context.Context, names []string, filter fleet.TeamFilter) (map[string]uint, error) {
+		return map[string]uint{
+			fleet.BuiltinLabelMacOS14Plus: 1,
+			fleet.BuiltinLabelIOS:         2,
+			fleet.BuiltinLabelIPadOS:      3,
+		}, nil
+	}
+	ds.HasAppleUpdateConfigProfileConfiguredFunc = func(ctx context.Context, teamID uint) (bool, error) { return false, nil }
+	ds.BulkUpsertHostDeviceNameEnforcementFunc = func(ctx context.Context, teamID uint) error { return nil }
+	ds.DeleteHostDeviceNameEnforcementForTeamFunc = func(ctx context.Context, teamID uint) error { return nil }
+
+	var emitted []activity_api.ActivityDetails
+	var emittedMu sync.Mutex
+	opts.ActivityMock.NewActivityFunc = func(_ context.Context, _ *activity_api.User, a activity_api.ActivityDetails) error {
+		emittedMu.Lock()
+		defer emittedMu.Unlock()
+		emitted = append(emitted, a)
+		return nil
+	}
+	nameTemplateActivities := func() []fleet.ActivityTypeEditedHostNameTemplate {
+		emittedMu.Lock()
+		defer emittedMu.Unlock()
+		var out []fleet.ActivityTypeEditedHostNameTemplate
+		for _, a := range emitted {
+			if act, ok := a.(fleet.ActivityTypeEditedHostNameTemplate); ok {
+				out = append(out, act)
+			}
+		}
+		return out
+	}
+
+	writeYAML := func(t *testing.T, body string) string {
+		f, err := os.CreateTemp(t.TempDir(), "*.yml")
+		require.NoError(t, err)
+		_, err = f.WriteString(body)
+		require.NoError(t, err)
+		require.NoError(t, f.Close())
+		return f.Name()
+	}
+	teamYAML := func(controlsSection string) string {
+		return fmt.Sprintf(`
+controls:
+%s
+queries:
+policies:
+agent_options:
+name: %s
+team_settings:
+  secrets:
+    - secret: test
+software:
+`, controlsSection, localTeamName)
+	}
+
+	// 0. Dry-run validates but does not persist, and still enforces the
+	// fleets-only rule (GitOps CI runs --dry-run on every PR).
+	t.Run("dry run does not persist a valid template", func(t *testing.T) {
+		ds.BulkUpsertHostDeviceNameEnforcementFuncInvoked = false
+		yml := writeYAML(t, teamYAML(fmt.Sprintf("  name_template: %q", template)))
+		_ = runAppForTest(t, []string{"gitops", "-f", yml, "--dry-run"})
+
+		require.Nil(t, savedTeam)
+		require.False(t, ds.BulkUpsertHostDeviceNameEnforcementFuncInvoked)
+		require.Empty(t, nameTemplateActivities())
+	})
+
+	t.Run("dry run rejects org-level template", func(t *testing.T) {
+		yml := writeYAML(t, fmt.Sprintf(`
+controls:
+  name_template: %q
+queries:
+policies:
+agent_options:
+org_settings:
+  server_settings:
+    server_url: %s
+  org_info:
+    contact_url: https://example.com/contact
+    org_logo_url: ""
+    org_logo_url_light_background: ""
+    org_name: %s
+  secrets:
+software:
+`, template, fleetServerURL, orgName))
+		_, err := runAppNoChecks([]string{"gitops", "-f", yml, "--dry-run"})
+		require.Error(t, err)
+		require.Contains(t, err.Error(), "only supported for fleets")
+	})
+
+	// 1. Setting the template on a fleet stores it and emits the activity.
+	t.Run("set template on fleet", func(t *testing.T) {
+		ds.BulkUpsertHostDeviceNameEnforcementFuncInvoked = false
+		yml := writeYAML(t, teamYAML(fmt.Sprintf("  name_template: %q", template)))
+		_ = runAppForTest(t, []string{"gitops", "-f", yml})
+
+		require.NotNil(t, savedTeam)
+		require.Equal(t, template, savedTeam.Config.MDM.HostNameTemplate)
+		require.True(t, ds.BulkUpsertHostDeviceNameEnforcementFuncInvoked)
+
+		acts := nameTemplateActivities()
+		require.Len(t, acts, 1)
+		require.NotNil(t, acts[0].HostNameTemplate)
+		require.Equal(t, template, *acts[0].HostNameTemplate)
+	})
+
+	// 2. Re-applying the same YAML is a no-op: no re-enqueue, no duplicate activity.
+	t.Run("idempotent re-apply", func(t *testing.T) {
+		ds.BulkUpsertHostDeviceNameEnforcementFuncInvoked = false
+		yml := writeYAML(t, teamYAML(fmt.Sprintf("  name_template: %q", template)))
+		_ = runAppForTest(t, []string{"gitops", "-f", yml})
+
+		require.Equal(t, template, savedTeam.Config.MDM.HostNameTemplate)
+		require.False(t, ds.BulkUpsertHostDeviceNameEnforcementFuncInvoked)
+		require.Len(t, nameTemplateActivities(), 1) // still just the one from step 1
+	})
+
+	// 3. Removing the key clears the template (declarative) and emits a null activity.
+	t.Run("clear template", func(t *testing.T) {
+		ds.DeleteHostDeviceNameEnforcementForTeamFuncInvoked = false
+		yml := writeYAML(t, teamYAML(""))
+		_ = runAppForTest(t, []string{"gitops", "-f", yml})
+
+		require.Empty(t, savedTeam.Config.MDM.HostNameTemplate)
+		require.True(t, ds.DeleteHostDeviceNameEnforcementForTeamFuncInvoked)
+
+		acts := nameTemplateActivities()
+		require.Len(t, acts, 2)
+		require.Nil(t, acts[1].HostNameTemplate) // cleared → null
+	})
+
+	// 4. An invalid variable surfaces the server's 422 validation message through fleetctl.
+	t.Run("invalid variable rejected", func(t *testing.T) {
+		yml := writeYAML(t, teamYAML(`  name_template: "$FLEET_VAR_HOST_END_USER_IDP_GROUPS"`))
+		_, err := runAppNoChecks([]string{"gitops", "-f", yml})
+		require.Error(t, err)
+		require.Contains(t, err.Error(), "is not supported in host name templates")
+	})
+
+	// 4b. A secret variable is rejected at the GitOps env-expansion layer (before
+	// the server), since $FLEET_SECRET_* is only allowed in profiles and scripts.
+	t.Run("secret variable rejected at expansion", func(t *testing.T) {
+		yml := writeYAML(t, teamYAML(`  name_template: "iPad $FLEET_SECRET_FOO"`))
+		_, err := runAppNoChecks([]string{"gitops", "-f", yml})
+		require.Error(t, err)
+		require.Contains(t, err.Error(), "FLEET_SECRET_")
+		require.Contains(t, err.Error(), "only allowed in profiles and scripts")
+	})
+
+	// 5. name_template in org-level controls is rejected (fleets only).
+	t.Run("rejected at org level", func(t *testing.T) {
+		yml := writeYAML(t, fmt.Sprintf(`
+controls:
+  name_template: %q
+queries:
+policies:
+agent_options:
+org_settings:
+  server_settings:
+    server_url: %s
+  org_info:
+    contact_url: https://example.com/contact
+    org_logo_url: ""
+    org_logo_url_light_background: ""
+    org_name: %s
+  secrets:
+software:
+`, template, fleetServerURL, orgName))
+		_, err := runAppNoChecks([]string{"gitops", "-f", yml})
+		require.Error(t, err)
+		require.Contains(t, err.Error(), "only supported for fleets")
+	})
+
+	// 6. name_template in no-team.yml controls is rejected (fleets only).
+	t.Run("rejected for no team", func(t *testing.T) {
+		globalFile := createGlobalFileBasic(t, fleetServerURL, orgName)
+
+		// The file must be named exactly "no-team.yml".
+		noTeamPath := filepath.Join(t.TempDir(), "no-team.yml")
+		noTeamFile, err := os.Create(noTeamPath)
+		require.NoError(t, err)
+		_, err = noTeamFile.WriteString(fmt.Sprintf(`
+controls:
+  name_template: %q
+policies:
+name: No team
+software:
+`, template))
+		require.NoError(t, err)
+		require.NoError(t, noTeamFile.Close())
+
+		_, err = runAppNoChecks([]string{"gitops", "-f", globalFile.Name(), "-f", noTeamPath})
+		require.Error(t, err)
+		require.Contains(t, err.Error(), "only supported for fleets")
+	})
+}
+
 func TestGitOpsWindowsOSUpdates(t *testing.T) {
 	license := &fleet.LicenseInfo{Tier: fleet.TierPremium, Expiration: time.Now().Add(24 * time.Hour)}
 	_, ds := testing_utils.RunServerWithMockedDS(

cmd/fleetctl/fleetctl/testdata/generateGitops/teamConfig.json

@@ -109,6 +109,7 @@
     },
     "mdm": {
         "enable_disk_encryption": true,
+        "name_template": "iPad $FLEET_VAR_HOST_HARDWARE_SERIAL",
         "macos_updates": {
             "minimum_version": "95.1",
             "deadline": "2020-12-31",

cmd/fleetctl/fleetctl/testdata/generateGitops/test_dir_premium/fleets/team-a-thumbsup.yml

@@ -41,6 +41,7 @@ controls:
     deadline: "2020-12-31"
     minimum_version: "95.1"
     update_new_hosts: true
+  name_template: iPad $FLEET_VAR_HOST_HARDWARE_SERIAL
   scripts:
   - path: "../lib/team-a-👍/scripts/Script B.ps1"
   windows_enabled_and_configured: true

pkg/spec/gitops.go

@@ -194,6 +194,7 @@ type GitOpsControls struct {
 	EnableDiskEncryption       any              `json:"enable_disk_encryption"`
 	EnableRecoveryLockPassword any              `json:"enable_recovery_lock_password"`
 	RequireBitLockerPIN        any              `json:"windows_require_bitlocker_pin,omitempty"`
+	NameTemplate               any              `json:"name_template"`
 	Scripts                    []fleet.BaseItem `json:"scripts"`
 
 	Defined bool
@@ -207,7 +208,8 @@ func (c GitOpsControls) Set() bool {
 		c.WindowsMigrationEnabled != nil || c.EnableDiskEncryption != nil || c.EnableRecoveryLockPassword != nil ||
 		len(c.Scripts) > 0 || c.AndroidEnabledAndConfigured != nil || c.AndroidSettings != nil ||
 		c.AppleRequireHardwareAttestation != nil || c.EnableTurnOnWindowsMDMManually != nil ||
-		c.WindowsEntraTenantIDs != nil || c.WindowsEntraClientIDs != nil || c.RequireBitLockerPIN != nil
+		c.WindowsEntraTenantIDs != nil || c.WindowsEntraClientIDs != nil || c.RequireBitLockerPIN != nil ||
+		c.NameTemplate != nil
 }
 
 type Policy struct {
@@ -1174,6 +1176,13 @@ func parseControls(top map[string]json.RawMessage, result *GitOps, logFn Logf, y
 		}
 	}
 
+	// Validate that name_template, if present, is a string.
+	if result.Controls.NameTemplate != nil {
+		if _, ok := result.Controls.NameTemplate.(string); !ok {
+			multiError = multierror.Append(multiError, fmt.Errorf("'controls.name_template' must be a string in %s", controlsFilePath))
+		}
+	}
+
 	// Find Fleet secrets in profiles
 	if result.Controls.MacOSSettings != nil {
 		// We are marshalling/unmarshalling to get the data into the fleet.MacOSSettings struct.

pkg/spec/gitops_test.go

@@ -409,6 +409,49 @@ func TestValidGitOpsYaml(t *testing.T) {
 	}
 }
 
+func TestGitOpsHostNameTemplate(t *testing.T) {
+	t.Parallel()
+
+	t.Run("valid string parses", func(t *testing.T) {
+		config := getTeamConfig([]string{"controls"})
+		config += "controls:\n  name_template: \"iPad $FLEET_VAR_HOST_HARDWARE_SERIAL\"\n"
+		gitops, err := gitOpsFromString(t, config)
+		require.NoError(t, err)
+		nameTemplate, ok := gitops.Controls.NameTemplate.(string)
+		require.True(t, ok, "name_template should be a string")
+		require.Equal(t, "iPad $FLEET_VAR_HOST_HARDWARE_SERIAL", nameTemplate)
+	})
+
+	t.Run("integer value rejected", func(t *testing.T) {
+		config := getTeamConfig([]string{"controls"})
+		config += "controls:\n  name_template: 42\n"
+		_, err := gitOpsFromString(t, config)
+		require.ErrorContains(t, err, "name_template")
+		require.ErrorContains(t, err, "must be a string")
+	})
+
+	t.Run("map value rejected", func(t *testing.T) {
+		config := getTeamConfig([]string{"controls"})
+		config += "controls:\n  name_template:\n    foo: bar\n"
+		_, err := gitOpsFromString(t, config)
+		require.ErrorContains(t, err, "name_template")
+		require.ErrorContains(t, err, "must be a string")
+	})
+
+	t.Run("null value treated as absent", func(t *testing.T) {
+		config := getTeamConfig([]string{"controls"})
+		config += "controls:\n  name_template:\n"
+		gitops, err := gitOpsFromString(t, config)
+		require.NoError(t, err)
+		require.Nil(t, gitops.Controls.NameTemplate)
+	})
+
+	t.Run("Set returns true when only name_template present", func(t *testing.T) {
+		c := GitOpsControls{NameTemplate: "iPad $FLEET_VAR_HOST_HARDWARE_SERIAL"}
+		require.True(t, c.Set())
+	})
+}
+
 func TestDuplicatePolicyNames(t *testing.T) {
 	t.Parallel()
 	config := getGlobalConfig([]string{"policies"})

server/service/client.go

@@ -2409,6 +2409,21 @@ func (c *Client) DoGitOps(
 		mdmAppConfig = team["mdm"].(map[string]interface{})
 	}
 
+	// name_template (host name template) is a fleets-only control.
+	nameTemplate := ""
+	if incoming.Controls.NameTemplate != nil {
+		var ok bool
+		nameTemplate, ok = incoming.Controls.NameTemplate.(string)
+		if !ok {
+			return nil, errors.New("controls.name_template must be a string")
+		}
+	}
+	if incoming.TeamName != nil && !incoming.IsNoTeam() {
+		mdmAppConfig["name_template"] = nameTemplate
+	} else if nameTemplate != "" {
+		return nil, errors.New(`name_template is only supported for fleets (teams); remove it from org-level and "No team" controls`)
+	}
+
 	if !incoming.IsNoTeam() {
 
 		// Common controls settings between org and team settings