diff --git a/go.mod b/go.mod
index fcd6bd7f7..ff34fac01 100644
--- a/go.mod
+++ b/go.mod
@@ -25,7 +25,8 @@ require (
 	github.com/gorilla/schema v1.2.0
 	github.com/hashicorp/go-cleanhttp v0.5.2
 	github.com/hashicorp/go-multierror v1.1.1
-	github.com/hashicorp/go-retryablehttp v0.7.1
+	github.com/hashicorp/go-retryablehttp v0.7.2
+	github.com/hashicorp/go-tfe v1.27.0
 	github.com/hashicorp/hcl/v2 v2.10.0
 	github.com/hashicorp/terraform-config-inspect v0.0.0-20221020162138-81db043ad408
 	github.com/iancoleman/strcase v0.2.0
@@ -43,7 +44,7 @@ require (
 	github.com/r3labs/sse/v2 v2.8.1
 	github.com/spf13/cobra v1.1.3
 	github.com/spf13/pflag v1.0.5
-	github.com/stretchr/testify v1.8.2
+	github.com/stretchr/testify v1.8.4
 	github.com/xanzy/go-gitlab v0.73.1
 	golang.org/x/exp v0.0.0-20230321023759-10a507213a29
 	golang.org/x/mod v0.8.0
@@ -84,7 +85,10 @@ require (
 	github.com/googleapis/gax-go/v2 v2.8.0 // indirect
 	github.com/gorilla/websocket v1.5.0 // indirect
 	github.com/hashicorp/errwrap v1.1.0 // indirect
+	github.com/hashicorp/go-slug v0.11.1 // indirect
+	github.com/hashicorp/go-version v1.6.0 // indirect
 	github.com/hashicorp/hcl v1.0.0 // indirect
+	github.com/hashicorp/jsonapi v0.0.0-20210826224640-ee7dae0fb22d // indirect
 	github.com/huandu/xstrings v1.3.2 // indirect
 	github.com/imdario/mergo v0.3.13 // indirect
 	github.com/inconshreveable/mousetrap v1.0.0 // indirect
diff --git a/go.sum b/go.sum
index d3d5f4126..a10f03b3e 100644
--- a/go.sum
+++ b/go.sum
@@ -299,6 +299,7 @@ github.com/googleapis/gax-go/v2 v2.0.5/go.mod h1:DWXyrwAJ9X0FpwwEdw+IPEYBICEFu5m
 github.com/googleapis/gax-go/v2 v2.8.0 h1:UBtEZqx1bjXtOQ5BVTkuYghXrr3N4V123VKJK67vJZc=
 github.com/googleapis/gax-go/v2 v2.8.0/go.mod h1:4orTrqY6hXxxaUL4LHIPl6lGo8vAE38/qKbhSAKP6QI=
 github.com/gopherjs/gopherjs v0.0.0-20181017120253-0766667cb4d1/go.mod h1:wJfORRmW1u3UXTncJ5qlYoELFm8eSnnEO6hX4iZ3EWY=
+github.com/gopherjs/gopherjs v1.17.2 h1:fQnZVsXk8uxXIStYb0N4bGk7jeyTalG/wsZjQ25dO0g=
 github.com/gorilla/handlers v1.5.1 h1:9lRY6j8DEeeBT10CvO9hGW0gmky0BprnvDI5vfhUHH4=
 github.com/gorilla/handlers v1.5.1/go.mod h1:t8XrUpc4KVXb7HGyJ4/cEnwQiaxrX/hz1Zv/4g96P1Q=
 github.com/gorilla/mux v1.8.0 h1:i40aqfkR1h2SlN9hojwV5ZA91wcXFOvkdNIeFDP5koI=
@@ -328,13 +329,20 @@ github.com/hashicorp/go-msgpack v0.5.3/go.mod h1:ahLV/dePpqEmjfWmKiqvPkv/twdG7iP
 github.com/hashicorp/go-multierror v1.0.0/go.mod h1:dHtQlpGsu+cZNNAkkCN/P3hoUDHhCYQXV3UM06sGGrk=
 github.com/hashicorp/go-multierror v1.1.1 h1:H5DkEtf6CXdFp0N0Em5UCwQpXMWke8IA0+lD48awMYo=
 github.com/hashicorp/go-multierror v1.1.1/go.mod h1:iw975J/qwKPdAO1clOe2L8331t/9/fmwbPZ6JB6eMoM=
-github.com/hashicorp/go-retryablehttp v0.7.1 h1:sUiuQAnLlbvmExtFQs72iFW/HXeUn8Z1aJLQ4LJJbTQ=
-github.com/hashicorp/go-retryablehttp v0.7.1/go.mod h1:vAew36LZh98gCBJNLH42IQ1ER/9wtLZZ8meHqQvEYWY=
+github.com/hashicorp/go-retryablehttp v0.7.2 h1:AcYqCvkpalPnPF2pn0KamgwamS42TqUDDYFRKq/RAd0=
+github.com/hashicorp/go-retryablehttp v0.7.2/go.mod h1:Jy/gPYAdjqffZ/yFGCFV2doI5wjtH1ewM9u8iYVjtX8=
 github.com/hashicorp/go-rootcerts v1.0.0/go.mod h1:K6zTfqpRlCUIjkwsN4Z+hiSfzSTQa6eBIzfwKfwNnHU=
+github.com/hashicorp/go-slug v0.11.1 h1:c6lLdQnlhUWbS5I7hw8SvfymoFuy6EmiFDedy6ir994=
+github.com/hashicorp/go-slug v0.11.1/go.mod h1:Ib+IWBYfEfJGI1ZyXMGNbu2BU+aa3Dzu41RKLH301v4=
 github.com/hashicorp/go-sockaddr v1.0.0/go.mod h1:7Xibr9yA9JjQq1JpNB2Vw7kxv8xerXegt+ozgdvDeDU=
 github.com/hashicorp/go-syslog v1.0.0/go.mod h1:qPfqrKkXGihmCqbJM2mZgkZGvKG1dFdvsLplgctolz4=
+github.com/hashicorp/go-tfe v1.27.0 h1:g+85TZfdUZOhIEkdDKRO8/q2JflhWB9Ne0V1xJOr4nE=
+github.com/hashicorp/go-tfe v1.27.0/go.mod h1:gu0DD6yf7K9P9IcuM4Wjl1grKYCa/o3oRRX5BQ+xEnY=
 github.com/hashicorp/go-uuid v1.0.0/go.mod h1:6SBZvOh/SIDV7/2o3Jml5SYk/TvGqwFJ/bN7x4byOro=
 github.com/hashicorp/go-uuid v1.0.1/go.mod h1:6SBZvOh/SIDV7/2o3Jml5SYk/TvGqwFJ/bN7x4byOro=
+github.com/hashicorp/go-uuid v1.0.3 h1:2gKiV6YVmrJ1i2CKKa9obLvRieoRGviZFL26PcT/Co8=
+github.com/hashicorp/go-version v1.6.0 h1:feTTfFNnjP967rlCxM/I9g701jU+RN74YKx2mOkIeek=
+github.com/hashicorp/go-version v1.6.0/go.mod h1:fltr4n8CU8Ke44wwGCBoEymUuxUHl09ZGVZPK5anwXA=
 github.com/hashicorp/go.net v0.0.1/go.mod h1:hjKkEWcCURg++eb33jQU7oqQcI9XDCnUzHA0oac0k90=
 github.com/hashicorp/golang-lru v0.5.0/go.mod h1:/m3WP610KZHVQ1SGc6re/UDhFvYD7pJ4Ao+sR/qLZy8=
 github.com/hashicorp/golang-lru v0.5.1/go.mod h1:/m3WP610KZHVQ1SGc6re/UDhFvYD7pJ4Ao+sR/qLZy8=
@@ -342,6 +350,8 @@ github.com/hashicorp/hcl v1.0.0 h1:0Anlzjpi4vEasTeNFn2mLJgTSwt0+6sfsiTG8qcWGx4=
 github.com/hashicorp/hcl v1.0.0/go.mod h1:E5yfLk+7swimpb2L/Alb/PJmXilQ/rhwaUYs4T20WEQ=
 github.com/hashicorp/hcl/v2 v2.10.0 h1:1S1UnuhDGlv3gRFV4+0EdwB+znNP5HmcGbIqwnSCByg=
 github.com/hashicorp/hcl/v2 v2.10.0/go.mod h1:FwWsfWEjyV/CMj8s/gqAuiviY72rJ1/oayI9WftqcKg=
+github.com/hashicorp/jsonapi v0.0.0-20210826224640-ee7dae0fb22d h1:9ARUJJ1VVynB176G1HCwleORqCaXm/Vx0uUi0dL26I0=
+github.com/hashicorp/jsonapi v0.0.0-20210826224640-ee7dae0fb22d/go.mod h1:Yog5+CPEM3c99L1CL2CFCYoSzgWm5vTU58idbRUaLik=
 github.com/hashicorp/logutils v1.0.0/go.mod h1:QIAnNjmIWmVIIkWDTG1z5v++HQmx9WQRO+LraFDTW64=
 github.com/hashicorp/mdns v1.0.0/go.mod h1:tL+uN++7HEJ6SQLQ2/p+z2pH24WQKWjBPkE0mNTz8vQ=
 github.com/hashicorp/memberlist v0.1.3/go.mod h1:ajVTdAv/9Im8oMAAj5G31PhhMCZJV2pPBoIllUwCN7I=
@@ -422,6 +432,7 @@ github.com/json-iterator/go v1.1.11/go.mod h1:KdQUCv79m/52Kvf8AW2vK1V8akMuk1QjK/
 github.com/json-iterator/go v1.1.12/go.mod h1:e30LSqwooZae/UwlEbR2852Gd8hjQvJoHmT4TnhNGBo=
 github.com/jstemmer/go-junit-report v0.0.0-20190106144839-af01ea7f8024/go.mod h1:6v2b51hI/fHJwM22ozAgKL4VKDeJcHhJFhtBdhmNjmU=
 github.com/jstemmer/go-junit-report v0.9.1/go.mod h1:Brl9GWCQeLvo8nXZwPNNblvFj/XSXhF0NWZEnDohbsk=
+github.com/jtolds/gls v4.20.0+incompatible h1:xdiiI2gbIgH/gLH7ADydsJ1uDOEzR8yvV7C0MuV77Wo=
 github.com/jtolds/gls v4.20.0+incompatible/go.mod h1:QJZ7F/aHp+rZTRtaJ1ow/lLfFfVYBRgL+9YlvaHOwJU=
 github.com/julienschmidt/httprouter v1.2.0/go.mod h1:SYymIcj16QtmaHHD7aYtjjsJG7VTCxuUUipMqKk8s4w=
 github.com/julienschmidt/httprouter v1.3.0/go.mod h1:JR6WtHb+2LUe8TCKY3cZOxFyyO8IZAc4RVcycCCAKdM=
@@ -614,7 +625,9 @@ github.com/sirupsen/logrus v1.6.0/go.mod h1:7uNnSEd1DgxDLC74fIahvMZmmYsHGZGEOFrf
 github.com/sirupsen/logrus v1.7.0/go.mod h1:yWOB1SBYBC5VeMP7gHvWumXLIWorT60ONWic61uBYv0=
 github.com/sirupsen/logrus v1.8.1/go.mod h1:yWOB1SBYBC5VeMP7gHvWumXLIWorT60ONWic61uBYv0=
 github.com/smartystreets/assertions v0.0.0-20180927180507-b2de0cb4f26d/go.mod h1:OnSkiWE9lh6wB0YB77sQom3nweQdgAjqCqsofrRNTgc=
+github.com/smartystreets/assertions v1.13.0 h1:Dx1kYM01xsSqKPno3aqLnrwac2LetPvN23diwyr69Qs=
 github.com/smartystreets/goconvey v1.6.4/go.mod h1:syvi0/a8iFYH4r/RixwvyeAJjdLS9QV7WQ/tjFTllLA=
+github.com/smartystreets/goconvey v1.7.2 h1:9RBaZCeXEQ3UselpuwUQHltGVXvdwm6cv1hgR6gDIPg=
 github.com/soheilhy/cmux v0.1.4/go.mod h1:IM3LyeVVIOuxMH7sFAkER9+bJ4dT7Ms6E4xg4kGIyLM=
 github.com/sowiner/lrserver v0.0.0-20230123160823-795409868576 h1:GpUML9gWdQuNHq2kmjl10l3Oa1LJ+CiJT6Q67AvV0dQ=
 github.com/sowiner/lrserver v0.0.0-20230123160823-795409868576/go.mod h1:hVi7G9lpYYueFVHEJdkIm9MaunP66DRm9I+sbPLJcSU=
@@ -648,8 +661,9 @@ github.com/stretchr/testify v1.7.0/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/
 github.com/stretchr/testify v1.7.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
 github.com/stretchr/testify v1.8.0/go.mod h1:yNjHg4UonilssWZ8iaSj1OCr/vHnekPRkoO+kdMU+MU=
 github.com/stretchr/testify v1.8.1/go.mod h1:w2LPCIKwWwSfY2zedu0+kehJoqGctiVI29o6fzry7u4=
-github.com/stretchr/testify v1.8.2 h1:+h33VjcLVPDHtOdpUCuF+7gSuG3yGIftsP1YvFihtJ8=
 github.com/stretchr/testify v1.8.2/go.mod h1:w2LPCIKwWwSfY2zedu0+kehJoqGctiVI29o6fzry7u4=
+github.com/stretchr/testify v1.8.4 h1:CcVxjf3Q8PM0mHUKJCdn+eZZtm5yQwehR5yeSVQQcUk=
+github.com/stretchr/testify v1.8.4/go.mod h1:sz/lmYIOXD/1dqDmKjjqLyZ2RngseejIcXlSw2iwfAo=
 github.com/subosito/gotenv v1.2.0/go.mod h1:N0PQaV/YGNqwC0u51sEeR/aUtSLEXKX9iv69rRypqCw=
 github.com/syndtr/gocapability v0.0.0-20200815063812-42c35b437635/go.mod h1:hkRG7XYTFWNJGYcbNJQlaLq0fg1yr4J4t/NcTQtrfww=
 github.com/tmc/grpc-websocket-proxy v0.0.0-20190109142713-0ad062ec5ee5/go.mod h1:ncp9v5uamzpCO7NfCPTXjqaC+bZgJeR0sMTm6dMHP7U=
@@ -1102,6 +1116,7 @@ gopkg.in/check.v1 v1.0.0-20190902080502-41f04d3bba15/go.mod h1:Co6ibVJAznAaIkqp8
 gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c h1:Hei/4ADfdWqJk1ZMxUNpqntNwaWcugrBjAiHlqqRiVk=
 gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c/go.mod h1:JHkPIbrfpd72SG/EVd6muEfDQjcINNoR0C8j2r3qZ4Q=
 gopkg.in/errgo.v2 v2.1.0/go.mod h1:hNsd1EY+bozCKY1Ytp96fpM3vjJbqLJn88ws8XvfDNI=
+gopkg.in/fsnotify.v1 v1.4.7 h1:xOHLXZwVvI9hhs+cLKq5+I5onOuwQLhQwiu63xxlHs4=
 gopkg.in/inconshreveable/log15.v2 v2.0.0-20180818164646-67afb5ed74ec/go.mod h1:aPpfJ7XW+gOuirDoZ8gHhLh3kZ1B08FtV2bbmy7Jv3s=
 gopkg.in/ini.v1 v1.51.0/go.mod h1:pNLf8WUiyNEtQjuu5G5vTm06TEv9tsIgeAvK8hOrP4k=
 gopkg.in/resty.v1 v1.12.0/go.mod h1:mDo4pnntr5jdWRML875a/NmxYqAlA73dVijT2AXvQQo=
diff --git a/internal/http/html/static/templates/content/workspace_edit.tmpl b/internal/http/html/static/templates/content/workspace_edit.tmpl
index f54e19f82..37d35bb62 100644
--- a/internal/http/html/static/templates/content/workspace_edit.tmpl
+++ b/internal/http/html/static/templates/content/workspace_edit.tmpl
@@ -179,6 +179,7 @@
         <button id="queue-destroy-plan-button" class="delete" {{ insufficient $canCreateRun }} onclick="return confirm('This will destroy all infrastructure in this workspace. Please confirm.')">
           Queue destroy plan
         </button>
+        <input type="hidden" name="connected" value="{{ ne .Workspace.Connection nil }}">
         <input name="operation" value="destroy-all" type="hidden">
       </form>
       <form action="{{ deleteWorkspacePath .Workspace.ID }}" method="POST">
diff --git a/internal/http/html/static/templates/content/workspace_get.tmpl b/internal/http/html/static/templates/content/workspace_get.tmpl
index 13928b201..7061edd53 100644
--- a/internal/http/html/static/templates/content/workspace_get.tmpl
+++ b/internal/http/html/static/templates/content/workspace_get.tmpl
@@ -30,6 +30,7 @@
       <div class="actions-container">
         <h5>Actions</h5>
         <form id="workspace-start-run-form" action="{{ startRunWorkspacePath .Workspace.ID }}" method="POST">
+          <input type="hidden" name="connected" value="{{ ne .Workspace.Connection nil }}">
           <select name="operation" id="start-run-operation" onchange="this.form.submit()">
             <option value="" selected>-- start run --</option>
             <option value="plan-only">plan only</option>
diff --git a/internal/integration/run_api_test.go b/internal/integration/run_api_test.go
new file mode 100644
index 000000000..9490907ee
--- /dev/null
+++ b/internal/integration/run_api_test.go
@@ -0,0 +1,84 @@
+package integration
+
+import (
+	"testing"
+
+	tfe "github.com/hashicorp/go-tfe"
+	"github.com/leg100/otf/internal"
+	"github.com/leg100/otf/internal/cloud"
+	"github.com/leg100/otf/internal/github"
+	"github.com/leg100/otf/internal/run"
+	"github.com/leg100/otf/internal/testutils"
+	"github.com/leg100/otf/internal/workspace"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// TestIntegration_RunAPI tests those parts of the run API that are not covered
+// by the `go-tfe` integration tests, i.e. behaviours that are specific to
+// OTF.
+func TestIntegration_RunAPI(t *testing.T) {
+	t.Parallel()
+
+	// setup daemon along with fake github repo
+	repo := cloud.NewTestRepo()
+	daemon := setup(t, nil,
+		github.WithRepo(repo),
+		github.WithArchive(testutils.ReadFile(t, "../testdata/github.tar.gz")),
+	)
+	org := daemon.createOrganization(t, ctx)
+	sub := daemon.createSubscriber(t, ctx)
+	_, token := daemon.createToken(t, ctx, nil)
+
+	tfeClient, err := tfe.NewClient(&tfe.Config{
+		Address:           "https://" + daemon.Hostname(),
+		Token:             string(token),
+		RetryServerErrors: true,
+	})
+	require.NoError(t, err)
+
+	// test the "magic string" behaviour specific to OTF: if
+	// run.PullVCSMagicString is specified for the config version ID then the
+	// config is pulled from the workspace's connected repo.
+	t.Run("create run using config from repo", func(t *testing.T) {
+		vcsProvider := daemon.createVCSProvider(t, ctx, org)
+		ws, err := daemon.CreateWorkspace(ctx, workspace.CreateOptions{
+			Name:         internal.String("connected-workspace"),
+			Organization: internal.String(org.Name),
+			ConnectOptions: &workspace.ConnectOptions{
+				RepoPath:      repo,
+				VCSProviderID: vcsProvider.ID,
+			},
+		})
+		require.NoError(t, err)
+
+		created, err := tfeClient.Runs.Create(ctx, tfe.RunCreateOptions{
+			ConfigurationVersion: &tfe.ConfigurationVersion{
+				ID: run.PullVCSMagicString,
+			},
+			Workspace: &tfe.Workspace{
+				ID: ws.ID,
+			},
+		})
+		require.NoError(t, err)
+
+		// wait for run to reach planned status
+		for event := range sub {
+			if r, ok := event.Payload.(*run.Run); ok {
+				switch r.Status {
+				case internal.RunErrored:
+					t.Fatal("run unexpectedly errored")
+				case internal.RunPlanned:
+					// run should have planned two resources (defined in the config from the
+					// github repo)
+					planned, err := daemon.GetRun(ctx, created.ID)
+					require.NoError(t, err)
+
+					assert.Equal(t, 2, planned.Plan.Additions)
+					return // success
+				}
+			}
+		}
+
+	})
+}
diff --git a/internal/integration/run_test.go b/internal/integration/run_test.go
index 364698429..247f6e2a4 100644
--- a/internal/integration/run_test.go
+++ b/internal/integration/run_test.go
@@ -6,9 +6,13 @@ import (
 
 	"github.com/leg100/otf/internal"
 	"github.com/leg100/otf/internal/auth"
+	"github.com/leg100/otf/internal/cloud"
 	"github.com/leg100/otf/internal/configversion"
 	"github.com/leg100/otf/internal/daemon"
+	"github.com/leg100/otf/internal/github"
 	"github.com/leg100/otf/internal/run"
+	"github.com/leg100/otf/internal/testutils"
+	"github.com/leg100/otf/internal/workspace"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 )
@@ -27,6 +31,34 @@ func TestRun(t *testing.T) {
 		require.NoError(t, err)
 	})
 
+	// test the "magic string" behaviour specific to OTF: if
+	// run.PullVCSMagicString is specified for the config version ID then the
+	// config is pulled from the workspace's connected repo.
+	t.Run("create run using config from repo", func(t *testing.T) {
+		// setup daemon along with fake github repo
+		repo := cloud.NewTestRepo()
+		daemon := setup(t, nil,
+			github.WithRepo(repo),
+			github.WithArchive(testutils.ReadFile(t, "../testdata/github.tar.gz")),
+		)
+		org := daemon.createOrganization(t, ctx)
+		vcsProvider := daemon.createVCSProvider(t, ctx, org)
+		ws, err := daemon.CreateWorkspace(ctx, workspace.CreateOptions{
+			Name:         internal.String("connected-workspace"),
+			Organization: internal.String(org.Name),
+			ConnectOptions: &workspace.ConnectOptions{
+				RepoPath:      repo,
+				VCSProviderID: vcsProvider.ID,
+			},
+		})
+		require.NoError(t, err)
+
+		_, err = daemon.CreateRun(ctx, ws.ID, run.RunCreateOptions{
+			ConfigurationVersionID: internal.String(run.PullVCSMagicString),
+		})
+		require.NoError(t, err)
+	})
+
 	t.Run("enqueue plan", func(t *testing.T) {
 		svc := setup(t, &config{Config: daemon.Config{DisableScheduler: true}})
 		run := svc.createRun(t, ctx, nil, nil)
diff --git a/internal/run/factory.go b/internal/run/factory.go
index 4757b6fbd..e9403fc61 100644
--- a/internal/run/factory.go
+++ b/internal/run/factory.go
@@ -2,27 +2,40 @@ package run
 
 import (
 	"context"
+	"fmt"
 
+	"github.com/leg100/otf/internal/cloud"
 	"github.com/leg100/otf/internal/configversion"
+	"github.com/leg100/otf/internal/workspace"
 )
 
 // factory constructs runs
 type factory struct {
 	ConfigurationVersionService
 	WorkspaceService
+	VCSProviderService
 }
 
-// NewRun constructs a new run at the beginning of its lifecycle using the
-// provided options.
+// NewRun constructs a new run using the provided options.
 func (f *factory) NewRun(ctx context.Context, workspaceID string, opts RunCreateOptions) (*Run, error) {
 	ws, err := f.GetWorkspace(ctx, workspaceID)
 	if err != nil {
 		return nil, err
 	}
 
+	// There are three possibilities for the ConfigurationVersionID value:
+	// (a) equals PullVCSMagicString in which case a config version is first
+	// created from the contents of the vcs repo connected to the workspace
+	// (b) non-nil, in which case it is deemed to be a configuration version id
+	// and an existing config version with that ID is retrieved.
+	// (c) nil, in which the latest config version is retrieved.
 	var cv *configversion.ConfigurationVersion
 	if opts.ConfigurationVersionID != nil {
-		cv, err = f.GetConfigurationVersion(ctx, *opts.ConfigurationVersionID)
+		if *opts.ConfigurationVersionID == PullVCSMagicString {
+			cv, err = f.createConfigVersionFromVCS(ctx, ws)
+		} else {
+			cv, err = f.GetConfigurationVersion(ctx, *opts.ConfigurationVersionID)
+		}
 	} else {
 		cv, err = f.GetLatestConfigurationVersion(ctx, workspaceID)
 	}
@@ -32,3 +45,35 @@ func (f *factory) NewRun(ctx context.Context, workspaceID string, opts RunCreate
 
 	return newRun(cv, ws, opts), nil
 }
+
+// createConfigVersionFromVCS creates a config version from the vcs repo
+// connected to the workspace using the contents of the vcs repo.
+func (f *factory) createConfigVersionFromVCS(ctx context.Context, ws *workspace.Workspace) (*configversion.ConfigurationVersion, error) {
+	if ws.Connection == nil {
+		return nil, workspace.ErrNoVCSConnection
+	}
+	client, err := f.GetVCSClient(ctx, ws.Connection.VCSProviderID)
+	if err != nil {
+		return nil, err
+	}
+	// use workspace branch if set
+	var ref *string
+	if ws.Branch != "" {
+		ref = &ws.Branch
+	}
+	tarball, err := client.GetRepoTarball(ctx, cloud.GetRepoTarballOptions{
+		Repo: ws.Connection.Repo,
+		Ref:  ref,
+	})
+	if err != nil {
+		return nil, fmt.Errorf("retrieving repository tarball: %w", err)
+	}
+	cv, err := f.CreateConfigurationVersion(ctx, ws.ID, configversion.ConfigurationVersionCreateOptions{})
+	if err != nil {
+		return nil, err
+	}
+	if err := f.UploadConfig(ctx, cv.ID, tarball); err != nil {
+		return nil, err
+	}
+	return cv, err
+}
diff --git a/internal/run/factory_test.go b/internal/run/factory_test.go
index 7713910f0..7ca6689d5 100644
--- a/internal/run/factory_test.go
+++ b/internal/run/factory_test.go
@@ -5,7 +5,10 @@ import (
 	"testing"
 
 	"github.com/leg100/otf/internal"
+	"github.com/leg100/otf/internal/cloud"
 	"github.com/leg100/otf/internal/configversion"
+	"github.com/leg100/otf/internal/repo"
+	"github.com/leg100/otf/internal/vcsprovider"
 	"github.com/leg100/otf/internal/workspace"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
@@ -15,7 +18,7 @@ func TestFactory(t *testing.T) {
 	ctx := context.Background()
 
 	t.Run("defaults", func(t *testing.T) {
-		f := testFactory(
+		f := newTestFactory(
 			&workspace.Workspace{},
 			&configversion.ConfigurationVersion{},
 		)
@@ -31,7 +34,7 @@ func TestFactory(t *testing.T) {
 	})
 
 	t.Run("speculative run", func(t *testing.T) {
-		f := testFactory(
+		f := newTestFactory(
 			&workspace.Workspace{},
 			&configversion.ConfigurationVersion{Speculative: true},
 		)
@@ -43,7 +46,7 @@ func TestFactory(t *testing.T) {
 	})
 
 	t.Run("plan-only run", func(t *testing.T) {
-		f := testFactory(
+		f := newTestFactory(
 			&workspace.Workspace{},
 			&configversion.ConfigurationVersion{},
 		)
@@ -55,7 +58,7 @@ func TestFactory(t *testing.T) {
 	})
 
 	t.Run("workspace auto-apply", func(t *testing.T) {
-		f := testFactory(
+		f := newTestFactory(
 			&workspace.Workspace{AutoApply: true},
 			&configversion.ConfigurationVersion{},
 		)
@@ -67,7 +70,7 @@ func TestFactory(t *testing.T) {
 	})
 
 	t.Run("run auto-apply", func(t *testing.T) {
-		f := testFactory(
+		f := newTestFactory(
 			&workspace.Workspace{},
 			&configversion.ConfigurationVersion{},
 		)
@@ -79,29 +82,67 @@ func TestFactory(t *testing.T) {
 
 		assert.True(t, got.AutoApply)
 	})
+
+	t.Run("pull from vcs", func(t *testing.T) {
+		f := newTestFactory(
+			&workspace.Workspace{
+				Connection: &repo.Connection{},
+			},
+			&configversion.ConfigurationVersion{},
+		)
+
+		got, err := f.NewRun(ctx, "", RunCreateOptions{
+			ConfigurationVersionID: internal.String(PullVCSMagicString),
+		})
+		require.NoError(t, err)
+
+		// fake config version service sets the config version ID to "created"
+		// if it was newly created
+		assert.Equal(t, "created", got.ConfigurationVersionID)
+	})
+
+	t.Run("pull from vcs workspace not connected error", func(t *testing.T) {
+		f := newTestFactory(
+			&workspace.Workspace{}, // workspace with no connection
+			&configversion.ConfigurationVersion{},
+		)
+
+		_, err := f.NewRun(ctx, "", RunCreateOptions{
+			ConfigurationVersionID: internal.String(PullVCSMagicString),
+		})
+		require.Equal(t, err, workspace.ErrNoVCSConnection)
+	})
 }
 
-func testFactory(ws *workspace.Workspace, cv *configversion.ConfigurationVersion) *factory {
+type (
+	fakeFactoryWorkspaceService struct {
+		ws *workspace.Workspace
+		workspace.Service
+	}
+	fakeFactoryConfigurationVersionService struct {
+		cv *configversion.ConfigurationVersion
+		configversion.Service
+	}
+	fakeFactoryVCSProviderService struct {
+		vcsprovider.Service
+	}
+	fakeFactoryCloudClient struct {
+		cloud.Client
+	}
+)
+
+func newTestFactory(ws *workspace.Workspace, cv *configversion.ConfigurationVersion) *factory {
 	return &factory{
 		WorkspaceService:            &fakeFactoryWorkspaceService{ws: ws},
 		ConfigurationVersionService: &fakeFactoryConfigurationVersionService{cv: cv},
+		VCSProviderService:          &fakeFactoryVCSProviderService{},
 	}
 }
 
-type fakeFactoryWorkspaceService struct {
-	ws *workspace.Workspace
-	workspace.Service
-}
-
 func (f *fakeFactoryWorkspaceService) GetWorkspace(context.Context, string) (*workspace.Workspace, error) {
 	return f.ws, nil
 }
 
-type fakeFactoryConfigurationVersionService struct {
-	cv *configversion.ConfigurationVersion
-	configversion.Service
-}
-
 func (f *fakeFactoryConfigurationVersionService) GetConfigurationVersion(context.Context, string) (*configversion.ConfigurationVersion, error) {
 	return f.cv, nil
 }
@@ -109,3 +150,19 @@ func (f *fakeFactoryConfigurationVersionService) GetConfigurationVersion(context
 func (f *fakeFactoryConfigurationVersionService) GetLatestConfigurationVersion(context.Context, string) (*configversion.ConfigurationVersion, error) {
 	return f.cv, nil
 }
+
+func (f *fakeFactoryConfigurationVersionService) CreateConfigurationVersion(context.Context, string, configversion.ConfigurationVersionCreateOptions) (*configversion.ConfigurationVersion, error) {
+	return &configversion.ConfigurationVersion{ID: "created"}, nil
+}
+
+func (f *fakeFactoryConfigurationVersionService) UploadConfig(context.Context, string, []byte) error {
+	return nil
+}
+
+func (f *fakeFactoryVCSProviderService) GetVCSClient(context.Context, string) (cloud.Client, error) {
+	return &fakeFactoryCloudClient{}, nil
+}
+
+func (f *fakeFactoryCloudClient) GetRepoTarball(context.Context, cloud.GetRepoTarballOptions) ([]byte, error) {
+	return nil, nil
+}
diff --git a/internal/run/run.go b/internal/run/run.go
index 1daae9b30..0df336830 100644
--- a/internal/run/run.go
+++ b/internal/run/run.go
@@ -17,6 +17,16 @@ const (
 	PlanFormatBinary = "bin"  // plan file in binary format
 	PlanFormatJSON   = "json" // plan file in json format
 
+	// When specified in place of a configuration version ID passed to
+	// RunCreateOptions this magic string instructs the run factory to
+	// automatically create a configuration version from the workspace connected
+	// vcs repo.
+	PullVCSMagicString = "__pull_vcs__"
+
+	PlanOnlyOperation     Operation = "plan-only"
+	PlanAndApplyOperation Operation = "plan-and-apply"
+	DestroyAllOperation   Operation = "destroy-all"
+
 	// defaultRefresh specifies that the state be refreshed prior to running a
 	// plan
 	defaultRefresh = true
@@ -27,6 +37,9 @@ var ErrInvalidRunStateTransition = errors.New("invalid run state transition")
 type (
 	PlanFormat string
 
+	// Run operation specifies the terraform execution mode.
+	Operation string
+
 	// Run is a terraform run.
 	Run struct {
 		ID                     string                  `json:"id"`
@@ -68,10 +81,19 @@ type (
 	// RunCreateOptions represents the options for creating a new run. See
 	// api/types/RunCreateOptions for documentation on each field.
 	RunCreateOptions struct {
-		IsDestroy              *bool
-		Refresh                *bool
-		RefreshOnly            *bool
-		Message                *string
+		IsDestroy   *bool
+		Refresh     *bool
+		RefreshOnly *bool
+		Message     *string
+		// Specifies the configuration version to use for this run. If the
+		// configuration version object is omitted, the run will be created using the
+		// workspace's latest configuration version.
+		//
+		// Alternatively, if PullVCSMagicString is specified, and the workspace
+		// is connected to a vcs repo, then a configuration version is
+		// automatically created from the vcs repo and the run uses that
+		// configuration version. If the workspace is not connected to a
+		// workspace then an error is returned.
 		ConfigurationVersionID *string
 		TargetAddrs            []string
 		ReplaceAddrs           []string
diff --git a/internal/run/service.go b/internal/run/service.go
index 6026c3940..7a0b2d3b0 100644
--- a/internal/run/service.go
+++ b/internal/run/service.go
@@ -122,6 +122,7 @@ func NewService(opts Options) *service {
 	svc.factory = &factory{
 		opts.ConfigurationVersionService,
 		opts.WorkspaceService,
+		opts.VCSProviderService,
 	}
 
 	svc.web = &webHandlers{
@@ -130,12 +131,6 @@ func NewService(opts Options) *service {
 		logsdb:           db,
 		logger:           opts.Logger,
 		svc:              &svc,
-		starter: &starter{
-			ConfigurationVersionService: opts.ConfigurationVersionService,
-			WorkspaceService:            opts.WorkspaceService,
-			VCSProviderService:          opts.VCSProviderService,
-			RunService:                  &svc,
-		},
 	}
 
 	// Register with broker so that it can relay run events
diff --git a/internal/run/starter.go b/internal/run/starter.go
deleted file mode 100644
index cd8f9ecb7..000000000
--- a/internal/run/starter.go
+++ /dev/null
@@ -1,95 +0,0 @@
-package run
-
-import (
-	"context"
-	"errors"
-	"fmt"
-
-	"github.com/leg100/otf/internal"
-	"github.com/leg100/otf/internal/cloud"
-	"github.com/leg100/otf/internal/configversion"
-)
-
-const (
-	PlanOnlyOperation     Operation = "plan-only"
-	PlanAndApplyOperation Operation = "plan-and-apply"
-	DestroyAllOperation   Operation = "destroy-all"
-)
-
-type (
-	// starter starts a run triggered via the UI (whereas the terraform CLI takes
-	// care of calling all the API endpoints to start a run itself).
-	starter struct {
-		ConfigurationVersionService
-		WorkspaceService
-		VCSProviderService
-		RunService
-	}
-
-	// Run operation specifies the terraform execution mode.
-	Operation string
-)
-
-func (rs *starter) startRun(ctx context.Context, workspaceID string, op Operation) (*Run, error) {
-	var (
-		planOnly bool
-		destroy  bool
-	)
-
-	switch op {
-	case PlanOnlyOperation:
-		planOnly = true
-	case PlanAndApplyOperation:
-		planOnly = false
-	case DestroyAllOperation:
-		destroy = true
-	default:
-		return nil, fmt.Errorf("invalid run operation: %s", op)
-	}
-
-	ws, err := rs.GetWorkspace(ctx, workspaceID)
-	if err != nil {
-		return nil, err
-	}
-
-	var cv *configversion.ConfigurationVersion
-	if ws.Connection != nil {
-		client, err := rs.GetVCSClient(ctx, ws.Connection.VCSProviderID)
-		if err != nil {
-			return nil, err
-		}
-		// use workspace branch if set
-		var ref *string
-		if ws.Branch != "" {
-			ref = &ws.Branch
-		}
-		tarball, err := client.GetRepoTarball(ctx, cloud.GetRepoTarballOptions{
-			Repo: ws.Connection.Repo,
-			Ref:  ref,
-		})
-		if err != nil {
-			return nil, fmt.Errorf("retrieving repository tarball: %w", err)
-		}
-		cv, err = rs.CreateConfigurationVersion(ctx, ws.ID, configversion.ConfigurationVersionCreateOptions{})
-		if err != nil {
-			return nil, err
-		}
-		if err := rs.UploadConfig(ctx, cv.ID, tarball); err != nil {
-			return nil, err
-		}
-	} else {
-		cv, err = rs.GetLatestConfigurationVersion(ctx, ws.ID)
-		if err != nil {
-			if errors.Is(err, internal.ErrResourceNotFound) {
-				return nil, fmt.Errorf("missing configuration: you need to either start a run via terraform, or connect a repository")
-			}
-			return nil, err
-		}
-	}
-
-	return rs.CreateRun(ctx, workspaceID, RunCreateOptions{
-		ConfigurationVersionID: internal.String(cv.ID),
-		IsDestroy:              &destroy,
-		PlanOnly:               &planOnly,
-	})
-}
diff --git a/internal/run/starter_test.go b/internal/run/starter_test.go
deleted file mode 100644
index 45ba596e5..000000000
--- a/internal/run/starter_test.go
+++ /dev/null
@@ -1,105 +0,0 @@
-package run
-
-import (
-	"context"
-	"testing"
-
-	"github.com/leg100/otf/internal/cloud"
-	"github.com/leg100/otf/internal/configversion"
-	"github.com/leg100/otf/internal/repo"
-	"github.com/leg100/otf/internal/vcsprovider"
-	"github.com/leg100/otf/internal/workspace"
-	"github.com/stretchr/testify/assert"
-	"github.com/stretchr/testify/require"
-)
-
-func TestStartRun(t *testing.T) {
-	ctx := context.Background()
-
-	t.Run("not connected to repo", func(t *testing.T) {
-		ws := &workspace.Workspace{}
-		cv := &configversion.ConfigurationVersion{}
-		want := &Run{}
-		starter := newTestStarter(fakeStarterService{
-			run:       want,
-			workspace: ws,
-			cv:        cv,
-		})
-
-		got, err := starter.startRun(ctx, ws.ID, PlanOnlyOperation)
-		require.NoError(t, err)
-		assert.Equal(t, want, got)
-	})
-
-	t.Run("connected to repo", func(t *testing.T) {
-		ws := &workspace.Workspace{Connection: &repo.Connection{}}
-		cv := &configversion.ConfigurationVersion{}
-		provider := &vcsprovider.VCSProvider{}
-		want := &Run{}
-		starter := newTestStarter(fakeStarterService{
-			run:       want,
-			workspace: ws,
-			cv:        cv,
-			provider:  provider,
-		})
-
-		got, err := starter.startRun(ctx, ws.ID, PlanOnlyOperation)
-		require.NoError(t, err)
-		assert.Equal(t, want, got)
-	})
-}
-
-type (
-	fakeStarterService struct {
-		run       *Run
-		workspace *workspace.Workspace
-		cv        *configversion.ConfigurationVersion
-		provider  *vcsprovider.VCSProvider
-
-		WorkspaceService
-		VCSProviderService
-		ConfigurationVersionService
-		RunService
-	}
-
-	fakeStartRunCloudClient struct {
-		cloud.Client
-	}
-)
-
-func newTestStarter(svc fakeStarterService) *starter {
-	return &starter{
-		ConfigurationVersionService: &svc,
-		VCSProviderService:          &svc,
-		WorkspaceService:            &svc,
-		RunService:                  &svc,
-	}
-}
-
-func (f *fakeStarterService) GetWorkspace(context.Context, string) (*workspace.Workspace, error) {
-	return f.workspace, nil
-}
-
-func (f *fakeStarterService) CreateConfigurationVersion(context.Context, string, configversion.ConfigurationVersionCreateOptions) (*configversion.ConfigurationVersion, error) {
-	return f.cv, nil
-}
-
-func (f *fakeStarterService) GetLatestConfigurationVersion(context.Context, string) (*configversion.ConfigurationVersion, error) {
-	return f.cv, nil
-}
-
-func (f *fakeStarterService) UploadConfig(context.Context, string, []byte) error {
-	return nil
-}
-
-func (f *fakeStarterService) GetVCSClient(context.Context, string) (cloud.Client, error) {
-	return &fakeStartRunCloudClient{}, nil
-}
-
-func (f *fakeStarterService) CreateRun(context.Context, string, RunCreateOptions) (*Run, error) {
-	return f.run, nil
-}
-
-func (f *fakeStartRunCloudClient) GetRepoTarball(context.Context, cloud.GetRepoTarballOptions) ([]byte, error) {
-	return nil, nil
-}
diff --git a/internal/run/test_helpers.go b/internal/run/test_helpers.go
index 87104b407..049891652 100644
--- a/internal/run/test_helpers.go
+++ b/internal/run/test_helpers.go
@@ -71,6 +71,10 @@ func (f *fakeWebServices) GetWorkspace(context.Context, string) (*workspace.Work
 	return f.ws, nil
 }
 
+func (f *fakeWebServices) CreateRun(ctx context.Context, workspaceID string, opts RunCreateOptions) (*Run, error) {
+	return f.runs[0], nil
+}
+
 func (f *fakeWebServices) ListRuns(ctx context.Context, opts RunListOptions) (*RunList, error) {
 	return &RunList{
 		Items:      f.runs,
diff --git a/internal/run/web.go b/internal/run/web.go
index afd34eada..d3d47ae59 100644
--- a/internal/run/web.go
+++ b/internal/run/web.go
@@ -40,7 +40,7 @@ func (h *webHandlers) addHandlers(r *mux.Router) {
 	r = html.UIRouter(r)
 
 	r.HandleFunc("/workspaces/{workspace_id}/runs", h.list).Methods("GET")
-	r.HandleFunc("/workspaces/{workspace_id}/start-run", h.startRun).Methods("POST")
+	r.HandleFunc("/workspaces/{workspace_id}/start-run", h.createRun).Methods("POST")
 	r.HandleFunc("/runs/{run_id}", h.get).Methods("GET")
 	r.HandleFunc("/runs/{run_id}/widget", h.getWidget).Methods("GET")
 	r.HandleFunc("/runs/{run_id}/delete", h.delete).Methods("POST")
@@ -54,6 +54,37 @@ func (h *webHandlers) addHandlers(r *mux.Router) {
 	r.HandleFunc("/{organization_name}/{workspace_id}/runs/{run_id}", h.get).Methods("GET")
 }
 
+func (h *webHandlers) createRun(w http.ResponseWriter, r *http.Request) {
+	var params struct {
+		WorkspaceID string    `schema:"workspace_id,required"`
+		Operation   Operation `schema:"operation,required"`
+		Connected   bool      `schema:"connected,required"`
+	}
+	if err := decode.All(&params, r); err != nil {
+		h.Error(w, err.Error(), http.StatusUnprocessableEntity)
+		return
+	}
+
+	opts := RunCreateOptions{
+		IsDestroy: internal.Bool(params.Operation == DestroyAllOperation),
+		PlanOnly:  internal.Bool(params.Operation == PlanOnlyOperation),
+	}
+	// if run's workspace is connected to a VCS repo then pull config from
+	// the repo
+	if params.Connected {
+		opts.ConfigurationVersionID = internal.String(PullVCSMagicString)
+	}
+
+	run, err := h.svc.CreateRun(r.Context(), params.WorkspaceID, opts)
+	if err != nil {
+		html.FlashError(w, err.Error())
+		http.Redirect(w, r, paths.Workspace(params.WorkspaceID), http.StatusFound)
+		return
+	}
+
+	http.Redirect(w, r, paths.Run(run.ID), http.StatusFound)
+}
+
 func (h *webHandlers) list(w http.ResponseWriter, r *http.Request) {
 	var params struct {
 		internal.ListOptions
@@ -230,26 +261,6 @@ func (h *webHandlers) discard(w http.ResponseWriter, r *http.Request) {
 	http.Redirect(w, r, paths.Run(runID), http.StatusFound)
 }
 
-func (h *webHandlers) startRun(w http.ResponseWriter, r *http.Request) {
-	var params struct {
-		WorkspaceID string    `schema:"workspace_id,required"`
-		Operation   Operation `schema:"operation,required"`
-	}
-	if err := decode.All(&params, r); err != nil {
-		h.Error(w, err.Error(), http.StatusUnprocessableEntity)
-		return
-	}
-
-	run, err := h.starter.startRun(r.Context(), params.WorkspaceID, params.Operation)
-	if err != nil {
-		html.FlashError(w, err.Error())
-		http.Redirect(w, r, paths.Workspace(params.WorkspaceID), http.StatusFound)
-		return
-	}
-
-	http.Redirect(w, r, paths.Run(run.ID), http.StatusFound)
-}
-
 func (h *webHandlers) retry(w http.ResponseWriter, r *http.Request) {
 	runID, err := decode.Param("run_id", r)
 	if err != nil {
diff --git a/internal/run/web_test.go b/internal/run/web_test.go
index 280c398be..d7a4f4936 100644
--- a/internal/run/web_test.go
+++ b/internal/run/web_test.go
@@ -5,6 +5,7 @@ import (
 	"testing"
 
 	"github.com/leg100/otf/internal/http/html/paths"
+	"github.com/leg100/otf/internal/repo"
 	"github.com/leg100/otf/internal/testutils"
 	"github.com/leg100/otf/internal/workspace"
 	"github.com/stretchr/testify/assert"
@@ -71,13 +72,27 @@ func TestRuns_CancelHandler(t *testing.T) {
 	testutils.AssertRedirect(t, w, paths.Runs("ws-1"))
 }
 
-func TestWebHandlers_StartRun(t *testing.T) {
-	run := &Run{ID: "run-1"}
-	h := newTestWebHandlers(t, withRuns(run))
+func TestWebHandlers_CreateRun_Connected(t *testing.T) {
+	h := newTestWebHandlers(t,
+		withRuns(&Run{ID: "run-1"}),
+		withWorkspace(&workspace.Workspace{ID: "ws-123", Connection: &repo.Connection{}}),
+	)
+
+	q := "/?workspace_id=run-123&operation=plan-only&connected=true"
+	r := httptest.NewRequest("POST", q, nil)
+	w := httptest.NewRecorder()
+	h.createRun(w, r)
+	testutils.AssertRedirect(t, w, paths.Run("run-1"))
+}
+
+func TestWebHandlers_CreateRun_Unconnected(t *testing.T) {
+	h := newTestWebHandlers(t,
+		withRuns(&Run{ID: "run-1"}),
+	)
 
-	q := "/?workspace_id=run-123&operation=plan-only"
+	q := "/?workspace_id=run-123&operation=plan-only&connected=false"
 	r := httptest.NewRequest("POST", q, nil)
 	w := httptest.NewRecorder()
-	h.startRun(w, r)
+	h.createRun(w, r)
 	testutils.AssertRedirect(t, w, paths.Run("run-1"))
 }
diff --git a/internal/workspace/workspace.go b/internal/workspace/workspace.go
index b95e8048a..9de9708fe 100644
--- a/internal/workspace/workspace.go
+++ b/internal/workspace/workspace.go
@@ -23,6 +23,8 @@ const (
 	DefaultTerraformVersion = "1.4.6"
 )
 
+var ErrNoVCSConnection = errors.New("workspace is not connected to a vcs repo")
+
 type (
 	// Workspace is a terraform workspace.
 	Workspace struct {