Document how to multi-label on GHES (#98)

* Document how to multi-label on GHES

* Ensure labels are always provided

Author: rentziass

README.md

@@ -12,7 +12,7 @@ You do *not* need to adopt the full controller (and Kubernetes) to take advantag
 
 A runner scale set is a group of self-hosted runners that autoscales based on workflow demand. Here's how it works:
 
-1. **Registration**: You create a scale set with a name, which also serves as the label workflows use to target it (e.g., `runs-on: my-scale-set`). Multiple labels can be assigned per scale set. Like regular self-hosted runners, scale sets can be registered at the repository, organization, or enterprise level.
+1. **Registration**: You create a scale set with a name, which also serves as the label workflows use to target it (e.g., `runs-on: my-scale-set`). Multiple labels can be assigned per scale set (on GHES, this requires enabling a feature flag — see [GitHub Enterprise Server](#github-enterprise-server)). Like regular self-hosted runners, scale sets can be registered at the repository, organization, or enterprise level.
 2. **Polling**: Your scale set client continuously polls the API, reporting its maximum capacity (how many runners it can produce).
 3. **Job matching**: GitHub matches jobs to your scale set based on the label and runner group policies, just like regular self-hosted runners.
 4. **Scaling signal**: The API responds with how many runners your scale set needs online (`statistics.TotalAssignedJobs`).
@@ -153,6 +153,23 @@ You can find more details on required permissions in the [GitHub Docs](https://d
 
 GitHub Enterprise Server (GHES) is supported out of the box—just use your GHES URL when creating the client.
 
+### GitHub Enterprise Server
+
+#### Multiple labels per scale set
+
+Assigning more than one label to a scale set is supported on **GHES 3.18 and later** and requires the `DistributedTask.AllowRunnerScaleSetCustomLabels` feature flag to be enabled on the appliance. Without it, the scale set name is used as the only label, and any additional labels you provide are silently dropped.
+
+- **GHES 3.18 – 3.20:** the flag is **off by default**. A site admin needs to enable it on the appliance:
+
+  ```bash
+  # SSH into the GHES appliance as admin
+  ghe-actions-console -s actions
+  # In the LightRail prompt:
+  Set-FeatureFlag -FeatureName DistributedTask.AllowRunnerScaleSetCustomLabels -State On
+  ```
+
+- **GHES 3.21 and later:** the flag is **on by default**, no action required.
+
 ---
 
 ## Security Notes

client.go

@@ -5,6 +5,7 @@ import (
 	"bytes"
 	"context"
 	"encoding/json"
+	"errors"
 	"fmt"
 	"io"
 	"maps"
@@ -388,11 +389,27 @@ func applyDefaultLabelTypes(runnerScaleSet *RunnerScaleSet) {
 	}
 }
 
+func ensureLabels(runnerScaleSet *RunnerScaleSet) error {
+	if len(runnerScaleSet.Labels) > 0 {
+		return nil
+	}
+
+	if runnerScaleSet.Name == "" {
+		return errors.New("runner scale set must have a name or at least one label")
+	}
+
+	runnerScaleSet.Labels = []Label{{Name: runnerScaleSet.Name, Type: "System"}}
+	return nil
+}
+
 // CreateRunnerScaleSet creates a new runner scale set. Note that runner scale set names must be unique within a runner group.
 func (c *Client) CreateRunnerScaleSet(ctx context.Context, runnerScaleSet *RunnerScaleSet) (*RunnerScaleSet, error) {
 	c.mu.Lock()
 	defer c.mu.Unlock()
 
+	if err := ensureLabels(runnerScaleSet); err != nil {
+		return nil, fmt.Errorf("validating runner scale set: %w", err)
+	}
 	applyDefaultLabelTypes(runnerScaleSet)
 
 	body, err := json.Marshal(runnerScaleSet)

client_test.go

@@ -829,7 +829,13 @@ func TestCreateRunnerScaleSet(t *testing.T) {
 	}
 
 	scaleSetCreationDateTime := time.Date(1, time.January, 1, 0, 0, 0, 0, time.UTC)
-	runnerScaleSet := RunnerScaleSet{ID: 1, Name: "ScaleSet", CreatedOn: scaleSetCreationDateTime, RunnerSetting: RunnerSetting{}}
+	runnerScaleSet := RunnerScaleSet{
+		ID:            1,
+		Name:          "ScaleSet",
+		Labels:        []Label{{Name: "ScaleSet", Type: "System"}},
+		CreatedOn:     scaleSetCreationDateTime,
+		RunnerSetting: RunnerSetting{},
+	}
 
 	t.Run("Create runner scale set", func(t *testing.T) {
 		want := &runnerScaleSet
@@ -920,6 +926,76 @@ func TestCreateRunnerScaleSet(t *testing.T) {
 		expectedRetry := retryMax + 1
 		assert.Equalf(t, actualRetry, expectedRetry, "A retry was expected after the first request but got: %v", actualRetry)
 	})
+
+	t.Run("populates labels with the scale set name when none are provided", func(t *testing.T) {
+		var sentBody RunnerScaleSet
+		server := newActionsServer(t, http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			require.NoError(t, json.NewDecoder(r.Body).Decode(&sentBody))
+			rsl, err := json.Marshal(&runnerScaleSet)
+			require.NoError(t, err)
+			w.Write(rsl)
+		}))
+
+		client, err := newClient(
+			testSystemInfo,
+			server.configURLForOrg("my-org"),
+			auth,
+		)
+		require.NoError(t, err)
+
+		input := &RunnerScaleSet{Name: "my-scale-set"}
+		_, err = client.CreateRunnerScaleSet(ctx, input)
+		require.NoError(t, err)
+
+		expectedLabels := []Label{{Name: "my-scale-set", Type: "System"}}
+		assert.Equal(t, expectedLabels, sentBody.Labels, "expected the request body to default labels to the scale set name")
+		assert.Equal(t, expectedLabels, input.Labels, "expected the input to be populated with the default label")
+	})
+
+	t.Run("returns an error when both name and labels are empty", func(t *testing.T) {
+		called := false
+		server := newActionsServer(t, http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+			called = true
+		}))
+
+		client, err := newClient(
+			testSystemInfo,
+			server.configURLForOrg("my-org"),
+			auth,
+		)
+		require.NoError(t, err)
+
+		_, err = client.CreateRunnerScaleSet(ctx, &RunnerScaleSet{})
+		require.Error(t, err)
+		assert.False(t, called, "expected no request to be sent when validation fails")
+	})
+
+	t.Run("preserves caller-provided labels", func(t *testing.T) {
+		var sentBody RunnerScaleSet
+		server := newActionsServer(t, http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			require.NoError(t, json.NewDecoder(r.Body).Decode(&sentBody))
+			rsl, err := json.Marshal(&runnerScaleSet)
+			require.NoError(t, err)
+			w.Write(rsl)
+		}))
+
+		client, err := newClient(
+			testSystemInfo,
+			server.configURLForOrg("my-org"),
+			auth,
+		)
+		require.NoError(t, err)
+
+		input := &RunnerScaleSet{
+			Name:   "my-scale-set",
+			Labels: []Label{{Name: "linux"}, {Name: "x64"}},
+		}
+		_, err = client.CreateRunnerScaleSet(ctx, input)
+		require.NoError(t, err)
+
+		expectedLabels := []Label{{Name: "linux", Type: "System"}, {Name: "x64", Type: "System"}}
+		assert.Equal(t, expectedLabels, sentBody.Labels, "expected caller-provided labels to be preserved")
+	})
 }
 
 func TestUpdateRunnerScaleSet(t *testing.T) {