feat: support --platform and --pull in container.options (#1104)

Fixes https://gitea.com/gitea/runner/issues/667
Fixes https://gitea.com/gitea/runner/pulls/1103

`container.options` is parsed with docker/cli's `addFlags`, which omits the flags docker/cli registers on the `create` and `run` commands themselves. Those were rejected as unknown — most visibly `--platform`.

| Flag | Behavior | Why |
| --- | --- | --- |
| `--platform` | overrides the runner-wide container architecture | the only way to pick an image architecture per job, e.g. across a matrix |
| `--pull always\|missing\|never` | `always` forces a pull, `never` skips it | `force_pull` is runner-wide config today, with no per-job control |

Both are resolved in `NewContainer` because the image pull runs before the container is created and the two have to agree.

`--name`, `--quiet` and `--disable-content-trust` are now accepted and ignored, and `--use-api-socket` is rejected pointing at `container.docker_host`, so a valid `docker create` line no longer fails outright.

<sub>Written by Claude (Opus 4.8).</sub>

---------

Co-authored-by: bircni <bircni@icloud.com>
Reviewed-on: https://gitea.com/gitea/runner/pulls/1104
Reviewed-by: bircni <bircni@icloud.com>
Co-authored-by: silverwind <me@silverwind.io>

act/container/docker_create_flags.go

@@ -0,0 +1,86 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+//go:build !(WITHOUT_DOCKER || !(linux || darwin || windows || netbsd))
+
+package container
+
+import (
+	"errors"
+	"fmt"
+	"io"
+	"slices"
+
+	"github.com/kballard/go-shellquote"
+	"github.com/spf13/pflag"
+)
+
+const (
+	pullPolicyAlways  = "always"
+	pullPolicyMissing = "missing"
+	pullPolicyNever   = "never"
+)
+
+var pullPolicies = []string{pullPolicyAlways, pullPolicyMissing, pullPolicyNever}
+
+// createFlags are the flags docker/cli registers on the `create` and `run` commands
+// instead of in addFlags, so they are not part of containerOptions.
+type createFlags struct {
+	platform     string
+	pull         string
+	name         string
+	useAPISocket bool
+}
+
+func registerCreateFlags(flags *pflag.FlagSet) *createFlags {
+	cf := new(createFlags)
+	flags.StringVar(&cf.platform, "platform", "", "Set platform if server is multi-platform capable")
+	flags.StringVar(&cf.pull, "pull", pullPolicyMissing, `Pull image before creating ("always", "missing", "never")`)
+	flags.StringVar(&cf.name, "name", "", "Assign a name to the container")
+	flags.BoolVar(&cf.useAPISocket, "use-api-socket", false, "Bind mount Docker API socket and required auth")
+	// Accepted without effect: pull progress is only logged at debug level, and docker
+	// no longer implements content trust.
+	flags.BoolP("quiet", "q", false, "Suppress the pull output")
+	flags.Bool("disable-content-trust", true, "Skip image verification (deprecated)")
+	return cf
+}
+
+// parseContainerOptions parses a container options string. The flags are returned even
+// on error, holding whatever was read before the failure.
+func parseContainerOptions(options string) (*pflag.FlagSet, *containerOptions, *createFlags, error) {
+	flags := pflag.NewFlagSet("container_flags", pflag.ContinueOnError)
+	flags.SetOutput(io.Discard)
+	copts := addFlags(flags)
+	cf := registerCreateFlags(flags)
+
+	args, err := shellquote.Split(options)
+	if err != nil {
+		return flags, copts, cf, fmt.Errorf("Cannot split container options: '%s': '%w'", options, err)
+	}
+
+	if err := flags.Parse(args); err != nil {
+		return flags, copts, cf, fmt.Errorf("Cannot parse container options: '%s': '%w'", options, err)
+	}
+
+	return flags, copts, cf, nil
+}
+
+// createFlagsFromOptions reads the create-level flags that have to be known before the
+// container is created. Malformed options keep the defaults here and are reported by
+// mergeContainerConfigs at create time.
+func createFlagsFromOptions(options string) *createFlags {
+	_, _, cf, _ := parseContainerOptions(options)
+	return cf
+}
+
+func (cf *createFlags) validate() error {
+	if !slices.Contains(pullPolicies, cf.pull) {
+		return fmt.Errorf("invalid --pull option %q: must be one of %q", cf.pull, pullPolicies)
+	}
+
+	if cf.useAPISocket {
+		return errors.New("--use-api-socket is not supported, use the runner's container.docker_host setting to expose a docker socket")
+	}
+
+	return nil
+}

act/container/docker_create_flags_test.go

@@ -0,0 +1,61 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package container
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestCreateFlagsFromOptions(t *testing.T) {
+	for _, tc := range []struct {
+		options  string
+		platform string
+		pull     string
+	}{
+		{"", "", pullPolicyMissing},
+		{"-v /a:/b --platform=linux/arm64 --pull always", "linux/arm64", pullPolicyAlways},
+		{"--platform linux/arm/v7 --pull never", "linux/arm/v7", pullPolicyNever},
+		{`--platform "linux/amd64`, "", pullPolicyMissing}, // malformed, defaults kept
+	} {
+		t.Run(tc.options, func(t *testing.T) {
+			cf := createFlagsFromOptions(tc.options)
+			assert.Equal(t, tc.platform, cf.platform)
+			assert.Equal(t, tc.pull, cf.pull)
+		})
+	}
+}
+
+func TestCreateFlagsValidate(t *testing.T) {
+	for _, tc := range []struct {
+		options string
+		wantErr string
+	}{
+		{"--quiet --disable-content-trust --name mine", ""},
+		{"--pull sometimes", `invalid --pull option "sometimes"`},
+		{"--use-api-socket", "--use-api-socket is not supported"},
+	} {
+		t.Run(tc.options, func(t *testing.T) {
+			err := createFlagsFromOptions(tc.options).validate()
+			if tc.wantErr == "" {
+				require.NoError(t, err)
+				return
+			}
+			require.ErrorContains(t, err, tc.wantErr)
+		})
+	}
+}
+
+func TestNewContainerAppliesCreateFlags(t *testing.T) {
+	input := &NewContainerInput{Platform: "linux/amd64", Options: "--platform linux/arm64 --pull never"}
+	cr := NewContainer(input).(*containerReference)
+	assert.Equal(t, "linux/arm64", input.Platform)
+	assert.Equal(t, pullPolicyNever, cr.pullPolicy)
+
+	kept := &NewContainerInput{Platform: "linux/amd64", Options: "--privileged"}
+	NewContainer(kept)
+	assert.Equal(t, "linux/amd64", kept.Platform)
+}

act/container/docker_run.go

@@ -35,7 +35,6 @@ import (
 	"github.com/go-git/go-git/v5/plumbing/format/gitignore"
 	"github.com/gobwas/glob"
 	"github.com/joho/godotenv"
-	"github.com/kballard/go-shellquote"
 	"github.com/moby/moby/api/pkg/stdcopy"
 	"github.com/moby/moby/api/types/container"
 	"github.com/moby/moby/api/types/mount"
@@ -43,7 +42,6 @@ import (
 	"github.com/moby/moby/api/types/system"
 	"github.com/moby/moby/client"
 	specs "github.com/opencontainers/image-spec/specs-go/v1"
-	"github.com/spf13/pflag"
 )
 
 // drainGracePeriod bounds how long we wait for an output-copy goroutine to
@@ -57,6 +55,12 @@ const drainGracePeriod = 2 * time.Second
 func NewContainer(input *NewContainerInput) ExecutionsEnvironment {
 	cr := new(containerReference)
 	cr.input = input
+	// Resolved up front because the image pull runs before the container is created.
+	cf := createFlagsFromOptions(input.Options)
+	if cf.platform != "" {
+		cr.input.Platform = cf.platform
+	}
+	cr.pullPolicy = cf.pull
 	return cr
 }
 
@@ -137,6 +141,11 @@ func (cr *containerReference) Start(attach bool) common.Executor {
 }
 
 func (cr *containerReference) Pull(forcePull bool) common.Executor {
+	if cr.pullPolicy == pullPolicyNever {
+		return common.NewInfoExecutor("docker pull skipped image=%s, --pull=never in the options", cr.input.Image)
+	}
+	forcePull = forcePull || cr.pullPolicy == pullPolicyAlways
+
 	return common.
 		NewInfoExecutor("docker pull image=%s platform=%s username=%s forcePull=%t", cr.input.Image, cr.input.Platform, cr.input.Username, forcePull).
 		Then(
@@ -235,6 +244,7 @@ type containerReference struct {
 	cli        client.APIClient
 	id         string
 	input      *NewContainerInput
+	pullPolicy string
 	UID        int
 	GID        int
 	// attachDone is closed by the attach() streaming goroutine once it has
@@ -411,17 +421,13 @@ func (cr *containerReference) mergeContainerConfigs(ctx context.Context, config
 	}
 
 	// parse configuration from CLI container.options
-	flags := pflag.NewFlagSet("container_flags", pflag.ContinueOnError)
-	copts := addFlags(flags)
-
-	optionsArgs, err := shellquote.Split(input.Options)
+	flags, copts, cf, err := parseContainerOptions(input.Options)
 	if err != nil {
-		return nil, nil, fmt.Errorf("Cannot split container options: '%s': '%w'", input.Options, err)
+		return nil, nil, err
 	}
 
-	err = flags.Parse(optionsArgs)
-	if err != nil {
-		return nil, nil, fmt.Errorf("Cannot parse container options: '%s': '%w'", input.Options, err)
+	if err := cf.validate(); err != nil {
+		return nil, nil, fmt.Errorf("Cannot process container options: '%s': '%w'", input.Options, err)
 	}
 
 	// FIXME: If everything is fine after gitea/act v0.260.0, remove the following comment.
@@ -476,6 +482,9 @@ func (cr *containerReference) mergeContainerConfigs(ctx context.Context, config
 	}
 	hostConfig.Binds = binds
 	hostConfig.Mounts = mounts
+	if cf.name != "" {
+		logger.Warn("--name in the options will be ignored.")
+	}
 	if len(copts.netMode.Value()) > 0 {
 		logger.Warn("--network and --net in the options will be ignored.")
 	}

act/runner/run_context.go

@@ -454,37 +454,7 @@ func (rc *RunContext) startJobContainer() common.Executor {
 			rc.ServiceContainers = append(rc.ServiceContainers, c)
 		}
 
-		rc.cleanUpJobContainer = func(ctx context.Context) error {
-			reuseJobContainer := func(ctx context.Context) bool {
-				return rc.Config.ReuseContainers
-			}
-
-			if rc.JobContainer != nil {
-				return rc.JobContainer.Remove().IfNot(reuseJobContainer).
-					Then(container.NewDockerVolumeRemoveExecutor(rc.jobContainerName(), false)).IfNot(reuseJobContainer).
-					Then(container.NewDockerVolumeRemoveExecutor(rc.jobContainerName()+"-env", false)).IfNot(reuseJobContainer).
-					Then(func(ctx context.Context) error {
-						if len(rc.ServiceContainers) > 0 {
-							logger.Infof("Cleaning up services for job %s", rc.JobName)
-							if err := rc.stopServiceContainers()(ctx); err != nil {
-								logger.Errorf("Error while cleaning services: %v", err)
-							}
-						}
-						if createAndDeleteNetwork {
-							// clean network if it has been created by act
-							// if using service containers
-							// it means that the network to which containers are connecting is created by `runner`,
-							// so, we should remove the network at last.
-							logger.Infof("Cleaning up network for job %s, and network name is: %s", rc.JobName, networkName)
-							if err := container.NewDockerNetworkRemoveExecutor(networkName)(ctx); err != nil {
-								logger.Errorf("Error while cleaning network: %v", err)
-							}
-						}
-						return nil
-					})(ctx)
-			}
-			return nil
-		}
+		rc.cleanUpJobContainer = rc.cleanupJobResources(networkName, createAndDeleteNetwork)
 
 		// For Gitea, `jobContainerNetwork` should be the same as `networkName`
 		jobContainerNetwork := networkName
@@ -539,6 +509,41 @@ func (rc *RunContext) startJobContainer() common.Executor {
 	}
 }
 
+// cleanupJobResources removes everything the job created, continuing past failures.
+// Only job container and volume errors are returned, the rest are logged.
+func (rc *RunContext) cleanupJobResources(networkName string, createAndDeleteNetwork bool) common.Executor {
+	return func(ctx context.Context) error {
+		logger := common.Logger(ctx)
+		removeJobContainer := rc.JobContainer != nil && !rc.Config.ReuseContainers
+
+		var errs []error
+		if removeJobContainer {
+			errs = append(errs, rc.JobContainer.Remove()(ctx))
+		}
+		if len(rc.ServiceContainers) > 0 {
+			logger.Infof("Cleaning up services for job %s", rc.JobName)
+			if err := rc.stopServiceContainers()(ctx); err != nil {
+				logger.Errorf("Error while cleaning services: %v", err)
+			}
+		}
+		if removeJobContainer {
+			// after the containers using them, services can hold these via `--volumes-from`
+			name := rc.jobContainerName()
+			errs = append(errs,
+				container.NewDockerVolumeRemoveExecutor(name, false)(ctx),
+				container.NewDockerVolumeRemoveExecutor(name+"-env", false)(ctx))
+		}
+		if createAndDeleteNetwork {
+			// last, once every container has detached
+			logger.Infof("Cleaning up network for job %s, and network name is: %s", rc.JobName, networkName)
+			if err := container.NewDockerNetworkRemoveExecutor(networkName)(ctx); err != nil {
+				logger.Errorf("Error while cleaning network: %v", err)
+			}
+		}
+		return errors.Join(errs...)
+	}
+}
+
 func (rc *RunContext) execJobContainer(cmd []string, env map[string]string, user, workdir string) common.Executor { //nolint:unparam // pre-existing issue from nektos/act
 	return func(ctx context.Context) error {
 		return rc.JobContainer.Exec(cmd, env, user, workdir)(ctx)

act/runner/run_context_test.go

@@ -7,6 +7,7 @@ package runner
 import (
 	"bytes"
 	"context"
+	"errors"
 	"fmt"
 	"os"
 	"runtime"
@@ -451,6 +452,46 @@ func TestRunContextValidVolumes(t *testing.T) {
 	assert.Len(t, rc.validVolumes(), len(got), "repeated calls must be stable, not accumulate")
 }
 
+func TestCleanupJobResourcesCleansServicesWithoutJobContainer(t *testing.T) {
+	service := &containerMock{}
+	service.On("Remove").Return(func(context.Context) error { return nil }).Once()
+	service.On("Close").Return(func(context.Context) error { return nil }).Once()
+
+	rc := &RunContext{
+		Config:            &Config{},
+		ServiceContainers: []container.ExecutionsEnvironment{service},
+	}
+
+	err := rc.cleanupJobResources("external-network", false)(context.Background())
+	require.NoError(t, err)
+	service.AssertExpectations(t)
+}
+
+// cleanup used to bail out on a previous step's error and on a cancelled context
+func TestCleanupJobResourcesContinuesAfterFailure(t *testing.T) {
+	t.Setenv("DOCKER_HOST", "unix:///nonexistent.sock")
+
+	jobContainer := &containerMock{}
+	jobContainer.On("Remove").Return(func(context.Context) error { return errors.New("removal failed") }).Once()
+	service := &containerMock{}
+	service.On("Remove").Return(func(context.Context) error { return nil }).Once()
+	service.On("Close").Return(func(context.Context) error { return nil }).Once()
+
+	rc := &RunContext{
+		Name:              "job",
+		Config:            &Config{},
+		Run:               &model.Run{Workflow: &model.Workflow{Name: "wf"}, JobID: "job"},
+		JobContainer:      jobContainer,
+		ServiceContainers: []container.ExecutionsEnvironment{service},
+	}
+
+	ctx, cancel := context.WithCancel(context.Background())
+	cancel()
+	require.Error(t, rc.cleanupJobResources("job-network", true)(ctx))
+	jobContainer.AssertExpectations(t)
+	service.AssertExpectations(t)
+}
+
 // TestInterpolateOutputsIsPerMatrixCombo guards the matrix-output fix: combinations share one
 // *model.Job, so each must interpolate from its own pristine snapshot. Otherwise the first
 // combo's resolved value freezes the shared template and later combos can't resolve their own.