.gitlab-ci.yml

@@ -9,7 +9,7 @@ stages:
 - build
 - package
 - release
-- cleanup
+- docs
 
 variables:
   CI_IMAGE: registry.gitlab.com/gitlab-org/gitlab-runner/ci:1.8.7-2
@@ -130,51 +130,6 @@ clone test repo:
     - tmp/gitlab-test
     expire_in: 7d
 
-# Review docs base
-.review-docs: &review-docs
-  image: ruby:2.4-alpine
-  before_script:
-    - unset GPG_KEY
-    - gem install gitlab --no-doc
-    # We need to download the script rather than clone the repo since the
-    # review-docs-cleanup job will not be able to run when the branch gets
-    # deleted (when merging the MR).
-    - apk add --update openssl
-    - wget https://gitlab.com/gitlab-org/gitlab-ce/raw/master/scripts/trigger-build-docs
-    - chmod 755 trigger-build-docs
-  cache: {}
-  dependencies: []
-  variables:
-    GIT_STRATEGY: none
-  when: manual
-  only:
-    - branches
-
-# Trigger a docs build in gitlab-docs
-# Useful to preview the docs changes live
-# https://docs.gitlab.com/ee/development/writing_documentation.html#previewing-the-changes-live
-review-docs-deploy:
-  <<: *review-docs
-  stage: prebuild
-  environment:
-    name: review-docs/$CI_COMMIT_REF_SLUG
-    # DOCS_REVIEW_APPS_DOMAIN and DOCS_GITLAB_REPO_SUFFIX are secret variables
-    # Discussion: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/14236/diffs#note_40140693
-    url: http://$CI_ENVIRONMENT_SLUG.$DOCS_REVIEW_APPS_DOMAIN/$DOCS_GITLAB_REPO_SUFFIX
-    on_stop: review-docs-cleanup
-  script:
-    - ./trigger-build-docs deploy
-
-# Cleanup remote environment of gitlab-docs
-review-docs-cleanup:
-  <<: *review-docs
-  stage: cleanup
-  environment:
-    name: review-docs/$CI_COMMIT_REF_SLUG
-    action: stop
-  script:
-    - ./trigger-build-docs cleanup
-
 tests definitions:
   <<: *except_docs
   stage: prebuild
@@ -294,10 +249,7 @@ docs lint:
     - mv docs/ /tmp/gitlab-docs/content/$DOCS_GITLAB_REPO_SUFFIX
     - cd /tmp/gitlab-docs
     # Lint Markdown
-    # https://github.com/markdownlint/markdownlint/blob/master/docs/RULES.md
-    - bundle exec mdl content/$DOCS_GITLAB_REPO_SUFFIX/**/*.md --rules \
-        MD001,MD002,MD003,MD005,MD006,MD009,MD010,MD011,MD012,MD018,MD019,MD022,\
-        MD023,MD025,MD027,MD028,MD029,MD030,MD031,MD032,MD034,MD037,MD038,MD039
+    - markdownlint --config $CI_PROJECT_DIR/.markdownlint.json content/$DOCS_GITLAB_REPO_SUFFIX/**/*.md
     # Build HTML from Markdown
     - bundle exec nanoc
     # Check the internal links
@@ -394,6 +346,7 @@ test junit report:
       junit: out/junit/report.xml
 
 .check windows test failures:
+  <<: *except_docs
   stage: coverage
   script:
   - ./scripts/check_windows_failures
@@ -500,7 +453,8 @@ package-rpm: *packages
   - if (Test-Path env:GPG_KEY) { Remove-Item Env:GPG_KEY }
   script:
   - .\ci\build_release_windows_images.ps1
-
+  dependencies:
+  - helper images
 
 .release: &release
   <<: *except_docs
@@ -674,3 +628,52 @@ static QA:
       jq -C . gl-code-quality-report.json
       exit 1
     fi
+
+#
+# Docs stage
+#
+
+# Review docs base
+.review-docs: &review-docs
+  image: ruby:2.6-alpine
+  before_script:
+    - unset GPG_KEY
+    - gem install gitlab --no-doc
+    # We need to download the script rather than clone the repo since the
+    # review-docs-cleanup job will not be able to run when the branch gets
+    # deleted (when merging the MR).
+    - apk add --update openssl
+    - wget https://gitlab.com/gitlab-org/gitlab-ce/raw/master/scripts/trigger-build-docs
+    - chmod 755 trigger-build-docs
+  cache: {}
+  dependencies: []
+  variables:
+    GIT_STRATEGY: none
+  when: manual
+  only:
+    - branches
+
+# Trigger a docs build in gitlab-docs
+# Useful to preview the docs changes live
+# https://docs.gitlab.com/ee/development/writing_documentation.html#previewing-the-changes-live
+review-docs-deploy:
+  <<: *review-docs
+  stage: docs
+  environment:
+    name: review-docs/$CI_COMMIT_REF_SLUG
+    # DOCS_REVIEW_APPS_DOMAIN and DOCS_GITLAB_REPO_SUFFIX are secret variables
+    # Discussion: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/14236/diffs#note_40140693
+    url: http://$CI_ENVIRONMENT_SLUG.$DOCS_REVIEW_APPS_DOMAIN/$DOCS_GITLAB_REPO_SUFFIX
+    on_stop: review-docs-cleanup
+  script:
+    - ./trigger-build-docs deploy
+
+# Cleanup remote environment of gitlab-docs
+review-docs-cleanup:
+  <<: *review-docs
+  stage: docs
+  environment:
+    name: review-docs/$CI_COMMIT_REF_SLUG
+    action: stop
+  script:
+    - ./trigger-build-docs cleanup

.markdownlint.json

+{
+  "default": true,
+  "first-header-h1": true,
+  "header-style": {
+    "style": "atx"
+  },
+  "ul-style": {
+    "style": "dash"
+  },
+  "line-length": false,
+  "commands-show-output": false,
+  "no-duplicate-header": {
+    "allow_different_nesting": true
+  },
+  "no-trailing-punctuation": {
+    "punctuation": ".,;:!。，；：！？"
+  },
+  "ol-prefix": {
+    "style": "one"
+  },
+  "no-inline-html": false,
+  "hr-style": {
+    "style": "---"
+  },
+  "no-emphasis-as-heading": false,
+  "fenced-code-language": false,
+  "first-line-h1": false,
+  "code-block-style": {
+    "style": "fenced"
+  }
+}

CHANGELOG.md

+v12.2.0 (2019-08-22)
+
+- Update docs executor titles !1454
+- Only default to Powershell on Windows if no other shell is specified !1457
+- Add more MDL rules !1462
+- Add PROCESS.md !1410
+- Fix wrong rc script for freebsd. !1418
+- Allow to build development version of DEB, RPM and Docker with make !824
+- Add custom executor documentation !1416
+- docs: clarify the requirements for pinning !823
+- Adds explanation of our review label system. !1461
+- Use FreeBSD's built-in stop and status scriplets from /etc/rc.subr !757
+- Fix typo on security docs !956
+- Update doc about Debian version !1464
+- Move note to subsection !1469
+- Correct spelling in help string !1471
+- Force an opt-out from Docker Machine bugsnag report !1443
+- Improved go install instructions for macOS !1472
+- Fix some linting issues !1424
+- Make it clear what is the default shell for Windows !1474
+- Add LXD example for custom executor !1439
+- Add libvirt custom executor example !1456
+- Update self-signed certificate docs for Windows service !1466
+- Docs/update min docker version !1480
+- Docs: Fix typo in custom executor !1479
+- Track Windows tests failures !1450
+- Add requirements for contributing new hardware architectures !1478
+- Fix markdown in runner docs (part 1) !1483
+- Fix markdown in runner docs (part 2) !1484
+- Update docs to specify default shell of OS !1485
+- Further clarify Docker requirements !1486
+- Fix typo and spacing in two runner docs !1487
+- docs: gitlab-runner helper image has no arm64 build yet !1489
+- Fix custom executor default config on register !1491
+- Update Windows test failures !1490
+- Expand markdown lint rules in runner !1492
+- Fix PowerShell capitalization !1497
+- Quarantine more windows tests !1499
+- Update tracked Windows tests failures list !1502
+- Quarantine windows tests !1501
+- Add docs for tls_verify config field !1493
+- Reorder methods in abstract.go to bring calees closer to the callers !1481
+- Update docs about bash on windows not working !1498
+- Cleanup commands/config.go !1494
+- Switch to DinD TLS for GitLab CI !1504
+- Add .gitattributes !1122
+- Prevent running multiple instances of the gitlab-runner process using the same configuration file !1496
+- Update test assertion !1510
+- Remove need for externally configured variable !1512
+- Change CI_COMMIT_REF to CI_COMMIT_SHA in docs !1513
+- Update reference to CI_COMMIT_REF to CI_COMMIT_SHA !1514
+- Configuration file template for registration command !1263
+- Update AWS autoscaling docs !1518
+- Add test for <at> and <colon> masking !1516
+
 v12.1.0 (2019-07-22)
 
 - Extend custom executor with configuration injects !1449

Gopkg.lock

@@ -411,11 +411,12 @@
   revision = "bf9dde6d0d2c004a008c27aaee91170c786f6db8"
 
 [[projects]]
-  digest = "1:ff6e83dd3b5a66d41c58a3d5e144bd06fcd4c376fd1a84379ad8c9a7dd308643"
+  digest = "1:158a976af1c463daebfa72efdfb66ccd78edfa475ed6d66937744bca05ee6c9c"
   name = "github.com/imdario/mergo"
   packages = ["."]
   pruneopts = "N"
-  revision = "50d4dbd4eb0e84778abe37cefef140271d96fade"
+  revision = "7c29201646fa3de8506f701213473dd407f19646"
+  version = "v0.3.7"
 
 [[projects]]
   digest = "1:485d36dae750af66fac78a968360bb1eb5a635d9d1e3a3b92116556cc2d45b6a"
@@ -1066,6 +1067,7 @@
     "github.com/gorilla/mux",
     "github.com/gorilla/websocket",
     "github.com/hashicorp/go-version",
+    "github.com/imdario/mergo",
     "github.com/jpillora/backoff",
     "github.com/kardianos/osext",
     "github.com/kr/pty",

Gopkg.toml

@@ -166,6 +166,10 @@ ignored = ["test", "appengine"]
   name = "github.com/gofrs/flock"
   branch = "master"
 
+[[constraint]]
+  name = "github.com/imdario/mergo"
+  version = "v0.3.7"
+
 ##
 ## Refrain innovations ;)
 ##
@@ -230,10 +234,6 @@ ignored = ["test", "appengine"]
   name = "github.com/gorilla/mux"
   revision = "599cba5e7b6137d46ddf58fb1765f5d928e69604"
 
-[[override]]
-  name = "github.com/imdario/mergo"
-  revision = "50d4dbd4eb0e84778abe37cefef140271d96fade"
-
 [[override]]
   name = "github.com/jonboulle/clockwork"
   revision = "e3653ace2d63753697e0e5b07b9393971c0bba9d"

Makefile

@@ -262,15 +262,6 @@ check-tags-in-changelog:
 		echo "$$tag:   \t $$state"; \
 	done
 
-prepare_release_checklist_issue_dry_run:
-	make prepare_release_checklist_issue opts="-dry-run"
-
-prepare_release_checklist_issue: opts ?= ""
-prepare_release_checklist_issue: $(GOPATH_SETUP)
-	@go run $(PKG)/scripts/prepare-release-checklist-issue \
-		-issue-template-file ".gitlab/issue_templates/Release Checklist.md" \
-		$(opts)
-
 update_feature_flags_docs: $(GOPATH_SETUP)
 	go run ./scripts/update-feature-flags-docs/main.go
 

VERSION

-12.2.0
\ No newline at end of file
+12.3.0
\ No newline at end of file

ci/build_release_windows_images.ps1

@@ -75,7 +75,7 @@ function Build-Image($tag)
         '--build-arg', "GIT_LFS_256_CHECKSUM=$Env:GIT_LFS_256_CHECKSUM"
     )
 
-    & 'docker' build -t "gitlab/gitlab-runner-helper:$tag" --force-rm $buildArgs -f $dockerFile $context
+    & 'docker' build -t "gitlab/gitlab-runner-helper:$tag" --force-rm --no-cache $buildArgs -f $dockerFile $context
     if ($LASTEXITCODE -ne 0) {
         throw ("Failed to build docker image" )
     }

ci/release_packagecloud

@@ -6,7 +6,7 @@ target=$(echo ${1} | cut -f 1 -d ' ')
 case "${target}" in
     bleeding)
         make packagecloud PACKAGE_CLOUD="runner/unstable" \
-                          DEB_PLATFORMS="debian/jessie debian/stretch ubuntu/xenial ubuntu/bionic" \
+                          DEB_PLATFORMS="debian/jessie debian/stretch debian/buster ubuntu/xenial ubuntu/bionic" \
                           RPM_PLATFORMS="el/7 fedora/30 fedora/29"
         ;;
     stable)

commands/register.go

@@ -8,6 +8,8 @@ import (
 	"runtime"
 	"strings"
 
+	"github.com/imdario/mergo"
+	"github.com/pkg/errors"
 	"github.com/sirupsen/logrus"
 	"github.com/urfave/cli"
 
@@ -16,6 +18,47 @@ import (
 	"gitlab.com/gitlab-org/gitlab-runner/network"
 )
 
+type configTemplate struct {
+	*common.Config
+
+	ConfigFile string `long:"config" env:"TEMPLATE_CONFIG_FILE" description:"Path to the configuration template file"`
+}
+
+func (c *configTemplate) Enabled() bool {
+	return c.ConfigFile != ""
+}
+
+func (c *configTemplate) MergeTo(config *common.RunnerConfig) error {
+	err := c.loadConfigTemplate()
+	if err != nil {
+		return errors.Wrap(err, "couldn't load configuration template file")
+	}
+
+	if len(c.Runners) != 1 {
+		return errors.New("configuration template must contain exactly one [[runners]] entry")
+	}
+
+	err = mergo.Merge(config, c.Runners[0])
+	if err != nil {
+		return errors.Wrap(err, "error while merging configuration with configuration template")
+	}
+
+	return nil
+}
+
+func (c *configTemplate) loadConfigTemplate() error {
+	config := common.NewConfig()
+
+	err := config.LoadConfig(c.ConfigFile)
+	if err != nil {
+		return err
+	}
+
+	c.Config = config
+
+	return nil
+}
+
 type RegisterCommand struct {
 	context    *cli.Context
 	network    common.Network
@@ -23,6 +66,9 @@ type RegisterCommand struct {
 	registered bool
 
 	configOptions
+
+	ConfigTemplate configTemplate `namespace:"template"`
+
 	TagList           string `long:"tag-list" env:"RUNNER_TAG_LIST" description:"Tag list"`
 	NonInteractive    bool   `short:"n" long:"non-interactive" env:"REGISTER_NON_INTERACTIVE" description:"Run registration unattended"`
 	LeaveRunner       bool   `long:"leave-runner" env:"REGISTER_LEAVE_RUNNER" description:"Don't remove runner if registration fails"`
@@ -336,6 +382,9 @@ func (s *RegisterCommand) Execute(context *cli.Context) {
 
 	s.askExecutor()
 	s.askExecutorOptions()
+
+	s.mergeTemplate()
+
 	s.addRunner(&s.RunnerConfig)
 	err = s.saveConfig()
 	if err != nil {
@@ -345,6 +394,19 @@ func (s *RegisterCommand) Execute(context *cli.Context) {
 	logrus.Printf("Runner registered successfully. Feel free to start it, but if it's running already the config should be automatically reloaded!")
 }
 
+func (s *RegisterCommand) mergeTemplate() {
+	if !s.ConfigTemplate.Enabled() {
+		return
+	}
+
+	logrus.Infof("Merging configuration from template file %q", s.ConfigTemplate.ConfigFile)
+
+	err := s.ConfigTemplate.MergeTo(&s.RunnerConfig)
+	if err != nil {
+		logrus.WithError(err).Fatal("Could not handle configuration merging from template file")
+	}
+}
+
 func getHostname() string {
 	hostname, _ := os.Hostname()
 	return hostname

commands/register_test.go

@@ -8,6 +8,8 @@ import (
 	"os"
 	"testing"
 
+	"github.com/imdario/mergo"
+	"github.com/pkg/errors"
 	"github.com/sirupsen/logrus"
 	"github.com/sirupsen/logrus/hooks/test"
 	"github.com/stretchr/testify/assert"
@@ -71,13 +73,27 @@ func getLogrusOutput(t *testing.T, hook *test.Hook) string {
 	for _, entry := range hook.AllEntries() {
 		message, err := entry.String()
 		require.NoError(t, err)
+
 		buf.WriteString(message)
 	}
 
 	return buf.String()
 }
 
-func testRegisterCommandRun(t *testing.T, network common.Network, args ...string) {
+func testRegisterCommandRun(t *testing.T, network common.Network, args ...string) (content string, output string, err error) {
+	hook := test.NewGlobal()
+
+	defer func() {
+		output = getLogrusOutput(t, hook)
+
+		if r := recover(); r != nil {
+			// log panics forces exit
+			if e, ok := r.(*logrus.Entry); ok {
+				err = fmt.Errorf("command error: %s", e.Message)
+			}
+		}
+	}()
+
 	cmd := newRegisterCommand()
 	cmd.network = network
 
@@ -90,8 +106,31 @@ func testRegisterCommandRun(t *testing.T, network common.Network, args ...string
 		},
 	}
 
-	args = append([]string{"binary", "register"}, args...)
-	app.Run(args)
+	configFile, err := ioutil.TempFile("", "config.toml")
+	require.NoError(t, err)
+
+	err = configFile.Close()
+	require.NoError(t, err)
+
+	defer os.Remove(configFile.Name())
+
+	args = append([]string{
+		"binary", "register",
+		"-n",
+		"--config", configFile.Name(),
+		"--url", "http://gitlab.example.com/",
+		"--registration-token", "test-registration-token",
+		"--executor", "shell",
+	}, args...)
+
+	comandErr := app.Run(args)
+
+	fileContent, err := ioutil.ReadFile(configFile.Name())
+	require.NoError(t, err)
+
+	err = comandErr
+
+	return string(fileContent), "", err
 }
 
 func TestAccessLevelSetting(t *testing.T) {
@@ -114,27 +153,6 @@ func TestAccessLevelSetting(t *testing.T) {
 
 	for testName, testCase := range tests {
 		t.Run(testName, func(t *testing.T) {
-			hook := test.NewGlobal()
-
-			defer func() {
-				logrusOutput := getLogrusOutput(t, hook)
-
-				r := recover()
-				if r == nil {
-					assert.Contains(t, logrusOutput, "Runner registered successfully.")
-					assert.NotContains(t, logrusOutput, "Given access-level is not valid. Please refer to gitlab-runner register -h for the correct options.")
-					return
-				}
-
-				if _, ok := r.(*logrus.Entry); ok {
-					assert.NotContains(t, logrusOutput, "Runner registered successfully.")
-					assert.Contains(t, logrusOutput, "Given access-level is not valid. Please refer to gitlab-runner register -h for the correct options.")
-					return
-				}
-
-				assert.Fail(t, fmt.Sprintf("Unexpected panic: %v", r))
-			}()
-
 			network := new(common.MockNetwork)
 			defer network.AssertExpectations(t)
 
@@ -150,21 +168,173 @@ func TestAccessLevelSetting(t *testing.T) {
 					Once()
 			}
 
-			configFile, err := ioutil.TempFile("", "config.toml")
-			require.NoError(t, err)
-
-			configFile.Close()
-			defer os.Remove(configFile.Name())
-
 			arguments := []string{
-				"-n",
-				"--config", configFile.Name(),
-				"--url", "http://gitlab.example.com/",
-				"--registration-token", "test-registration-token",
-				"--executor", "shell",
 				"--access-level", string(testCase.accessLevel),
 			}
-			testRegisterCommandRun(t, network, arguments...)
+
+			_, output, err := testRegisterCommandRun(t, network, arguments...)
+
+			if testCase.failureExpected {
+				assert.EqualError(t, err, "command error: Given access-level is not valid. Please refer to gitlab-runner register -h for the correct options.")
+				assert.NotContains(t, output, "Runner registered successfully.")
+
+				return
+			}
+
+			assert.NoError(t, err)
+			assert.Contains(t, output, "Runner registered successfully.")
+		})
+	}
+}
+
+func TestConfigTemplate_Enabled(t *testing.T) {
+	tests := map[string]struct {
+		path          string
+		expectedValue bool
+	}{
+		"configuration file defined": {
+			path:          "/path/to/file",
+			expectedValue: true,
+		},
+		"configuration file not defined": {
+			path:          "",
+			expectedValue: false,
+		},
+	}
+
+	for tn, tc := range tests {
+		t.Run(tn, func(t *testing.T) {
+			configTemplate := &configTemplate{ConfigFile: tc.path}
+			assert.Equal(t, tc.expectedValue, configTemplate.Enabled())
+		})
+	}
+}
+
+func prepareConfigurationTemplateFile(t *testing.T, content string) (string, func()) {
+	file, err := ioutil.TempFile("", "config.template.toml")
+	require.NoError(t, err)
+
+	defer func() {
+		err = file.Close()
+		require.NoError(t, err)
+	}()
+
+	_, err = file.WriteString(content)
+	require.NoError(t, err)
+
+	cleanup := func() {
+		_ = os.Remove(file.Name())
+	}
+
+	return file.Name(), cleanup
+}
+
+var (
+	configTemplateMergeToInvalidConfiguration = `- , ;`
+
+	configTemplateMergeToEmptyConfiguration = ``
+
+	configTemplateMergeToTwoRunnerSectionsConfiguration = `
+[[runners]]
+[[runners]]`
+
+	configTemplateMergeToOverwritingConfiguration = `
+[[runners]]
+  token = "different_token"
+  executor = "docker"
+  limit = 100`
+
+	configTemplateMergeToAdditionalConfiguration = `
+[[runners]]
+  [runners.kubernetes]
+    [runners.kubernetes.volumes]
+      [[runners.kubernetes.volumes.empty_dir]]
+        name = "empty_dir"
+	    mount_path = "/path/to/empty_dir"
+	    medium = "Memory"`
+
+	configTemplateMergeToBaseConfiguration = &common.RunnerConfig{
+		RunnerCredentials: common.RunnerCredentials{
+			Token: "test-runner-token",
+		},
+		RunnerSettings: common.RunnerSettings{
+			Executor: "shell",
+		},
+	}
+)
+
+func TestConfigTemplate_MergeTo(t *testing.T) {
+	tests := map[string]struct {
+		templateContent string
+		config          *common.RunnerConfig
+
+		expectedError       error
+		assertConfiguration func(t *testing.T, config *common.RunnerConfig)
+	}{
+		"invalid template file": {
+			templateContent: configTemplateMergeToInvalidConfiguration,
+			config:          configTemplateMergeToBaseConfiguration,
+			expectedError:   errors.New("couldn't load configuration template file: Near line 1 (last key parsed '-'): expected key separator '=', but got ',' instead"),
+		},
+		"no runners in template": {
+			templateContent: configTemplateMergeToEmptyConfiguration,
+			config:          configTemplateMergeToBaseConfiguration,
+			expectedError:   errors.New("configuration template must contain exactly one [[runners]] entry"),
+		},
+		"multiple runners in template": {
+			templateContent: configTemplateMergeToTwoRunnerSectionsConfiguration,
+			config:          configTemplateMergeToBaseConfiguration,
+			expectedError:   errors.New("configuration template must contain exactly one [[runners]] entry"),
+		},
+		"template doesn't overwrite existing settings": {
+			templateContent: configTemplateMergeToOverwritingConfiguration,
+			config:          configTemplateMergeToBaseConfiguration,
+			assertConfiguration: func(t *testing.T, config *common.RunnerConfig) {
+				assert.Equal(t, configTemplateMergeToBaseConfiguration.Token, config.RunnerCredentials.Token)
+				assert.Equal(t, configTemplateMergeToBaseConfiguration.Executor, config.RunnerSettings.Executor)
+				assert.Equal(t, 100, config.Limit)
+			},
+			expectedError: nil,
+		},
+		"template adds additional content": {
+			templateContent: configTemplateMergeToAdditionalConfiguration,
+			config:          configTemplateMergeToBaseConfiguration,
+			assertConfiguration: func(t *testing.T, config *common.RunnerConfig) {
+				k8s := config.RunnerSettings.Kubernetes
+
+				require.NotNil(t, k8s)
+				require.NotEmpty(t, k8s.Volumes.EmptyDirs)
+				assert.Len(t, k8s.Volumes.EmptyDirs, 1)
+
+				emptyDir := k8s.Volumes.EmptyDirs[0]
+				assert.Equal(t, "empty_dir", emptyDir.Name)
+				assert.Equal(t, "/path/to/empty_dir", emptyDir.MountPath)
+				assert.Equal(t, "Memory", emptyDir.Medium)
+			},
+			expectedError: nil,
+		},
+		"error on merging": {
+			templateContent: configTemplateMergeToAdditionalConfiguration,
+			expectedError:   errors.Wrap(mergo.ErrNotSupported, "error while merging configuration with configuration template"),
+		},
+	}
+
+	for tn, tc := range tests {
+		t.Run(tn, func(t *testing.T) {
+			file, cleanup := prepareConfigurationTemplateFile(t, tc.templateContent)
+			defer cleanup()
+
+			configTemplate := &configTemplate{ConfigFile: file}
+			err := configTemplate.MergeTo(tc.config)
+
+			if tc.expectedError != nil {
+				assert.EqualError(t, err, tc.expectedError.Error())
+
+				return
+			}
+
+			assert.NoError(t, err)
+			tc.assertConfiguration(t, tc.config)
 		})
 	}
 }

common/build.go

@@ -389,10 +389,8 @@ func (b *Build) retryCreateExecutor(options ExecutorPrepareOptions, provider Exe
 		if err == nil {
 			break
 		}
-		if executor != nil {
-			executor.Cleanup()
-			executor = nil
-		}
+		executor.Cleanup()
+		executor = nil
 		if _, ok := err.(*BuildError); ok {
 			break
 		} else if options.Context.Err() != nil {

docs/best_practice/index.md

+# Best practice
+
+Below are some guidelines you should follow when you use and administer
+GitLab Runner.
+
+## Build Directory
+
+GitLab Runner will clone the repository to a path that exists under a
+base path better known as the _Builds Directory_. The default location
+of this base directory depends on the executor. For:
+
+- [Kubernetes](../executors/kubernetes.md),
+  [Docker](../executors/docker.md) and [Docker
+  Machine](../executors/docker_machine.md) executors it will be
+  `/builds` inside of the container.
+- [Shell](../executors/shell.md) executor it will be `$PWD/builds`.
+- [SSH](../executors/ssh.md), [VirtualBox](../executors/virtualbox.md)
+  and [Parallels](../executors/parallels.md) executors it will be
+  `~/builds` in the home directory of the user configured to handle the
+  SSH connection to the target machine.
+- [Custom](../executors/custom.md) executor no default is provided and
+  it must be explicitly configured, otherwise, the job will fail.
+
+The used _Builds Directory_ may be defined explicitly by the user with the
+[`builds_dir`](../configuration/advanced-configuration.md#the-runners-section)
+setting.
+
+TIP: **Tip:**
+You can also specify
+[`GIT_CLONE_PATH`](https://docs.gitlab.com/ee/ci/yaml/README.html#custom-build-directories)
+if you want to clone to a custom directory, and the guideline below
+doesn't apply.
+
+GitLab Runner will use the _Builds Directory_ for all the Jobs that it
+will run, but nesting them using a specific pattern
+`{builds_dir}/$RUNNER_TOKEN_KEY/$CONCURRENT_ID/$NAMESPACE/$PROJECT_NAME`.
+For example: `/builds/2mn-ncv-/0/user/playground`.
+
+GitLab Runner does not stop you from storing things inside of the
+_Builds Directory_. For example, you can store tools inside of
+`/builds/tools` that can be used during CI execution. We **HIGHLY**
+discourage this, you should never store anything inside of the _Builds
+Directory_. GitLab Runner should have total control over it and does not
+provide stability in such cases. If you have dependencies that are
+required for your CI, we recommend to have them installed in some other
+place.

docs/commands/README.md

@@ -245,6 +245,13 @@ gitlab-runner register
 
 > **Note:** Boolean parameters must be passed in the command line with `--key={true|false}`.
 
+#### `[[runners]]` configuration template file
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-runner/issues/4228) in GitLab Runner 12.2.
+
+Additional options can be easily configured during Runner registration using the
+[configuration template file](../register/index.md#runners-configuration-template-file) feature.
+
 ### gitlab-runner list
 
 This command lists all runners saved in the
@@ -302,13 +309,13 @@ Then use this information to unregister it, using one of the following commands.
 This operation cannot be undone, it will update the configuration file, so
 make sure to have a backup of `config.toml` before executing it.
 
-#### By URL and token:
+#### By URL and token
 
 ```bash
 gitlab-runner unregister --url http://gitlab.example.com/ --token t0k3n
 ```
 
-#### By name:
+#### By name
 
 > **Note:** If there is more than one runner with the given name, only the first one will be removed
 
@@ -316,7 +323,7 @@ gitlab-runner unregister --url http://gitlab.example.com/ --token t0k3n
 gitlab-runner unregister --name test-runner
 ```
 
-#### All Runners:
+#### All Runners
 
 ```bash
 gitlab-runner unregister --all-runners

docs/configuration/index.md

@@ -18,5 +18,6 @@ well as information how to set up Prometheus metrics:
 - [Runner monitoring](../monitoring/README.md) Learn how to monitor the Runner's behavior.
 - [Cleanup the Docker images automatically](https://gitlab.com/gitlab-org/gitlab-runner-docker-cleanup) A simple Docker application that automatically garbage collects the GitLab Runner caches and images when running low on disk space.
 - [Configure GitLab Runner to run behind a proxy](proxy.md) Learn how to set up a Linux proxy and configure GitLab Runner. Especially useful for the Docker executor.
+- [Best practice for using GitLab Runner](../best_practice/index.md).
 
 [TOML]: https://github.com/toml-lang/toml

docs/configuration/runner_autoscale_aws/index.md

 ---
-last_updated: 2019-01-28
+last_updated: 2019-08-21
 ---
 
 > **[Article Type](https://docs.gitlab.com/ee/development/writing_documentation.html#types-of-technical-articles):** Admin guide ||
@@ -18,7 +18,7 @@ scalable solution.
 ## Introduction
 
 In this tutorial, we'll explore how to properly configure a GitLab Runner in
-AWS that will serve as the bastion where it will spawn new Docker machines on
+AWS that will serve as the Runner Manager where it will spawn new Docker machines on
 demand.
 
 In addition, we'll make use of [Amazon's EC2 Spot instances][spot] which will
@@ -64,16 +64,16 @@ you can disable console login for that user. Keep the tab open or copy paste the
 security credentials in an editor as we'll use them later during the
 [Runner configuration](#the-runnersmachine-section).
 
-## Prepare the bastion instance
+## Prepare the Runner Manager instance
 
 The first step is to install GitLab Runner in an EC2 instance that will serve
-as the bastion that spawns new machines. This doesn't have to be a powerful
+as the Runner Manager that spawns new machines. This doesn't have to be a powerful
 machine since it will not run any jobs itself, a `t2.micro` instance will do.
 This machine will be a dedicated host since we need it always up and running,
 thus it will be the only standard cost.
 
 NOTE: **Note:**
-For the bastion instance, choose a distribution that both Docker and GitLab
+For the Runner Manager instance, choose a distribution that both Docker and GitLab
 Runner support, for example either Ubuntu, Debian, CentOS or RHEL will work fine.
 
 Install the prerequisites:
@@ -274,7 +274,8 @@ different options to be applied.
 
 NOTE: **Note:**
 The child instances will use by default Ubuntu 16.04 unless you choose a
-different AMI ID by setting `amazonec2-ami`.
+different AMI ID by setting `amazonec2-ami`. Set only [supported
+base operating systems for Docker Machine](https://docs.docker.com/machine/drivers/os-base/).
 
 NOTE: **Note:**
 If you specify `amazonec2-private-address-only=true` as one of the machine
@@ -402,7 +403,7 @@ it will continue to request new instances. This eventually will make 60 requests
 and then AWS won't accept any more. Then once the Spot price is acceptable, you
 are locked out for a bit because the call amount limit is exceeded.
 
-If you encounter that case, you can use the following command in the bastion
+If you encounter that case, you can use the following command in the Runner Manager
 machine to see the Docker Machines state:
 
 ```sh

docs/configuration/tls-self-signed.md

@@ -14,7 +14,7 @@ GitLab Runner provides these options:
 1. GitLab Runner reads the PEM (**DER format is not supported**) certificate from predefined file:
 
    - `/etc/gitlab-runner/certs/hostname.crt` on *nix systems when gitlab-runner is executed as root.
-   - `~/.gitlab-runner/certs/hostname.crt` on *nix systems when gitlab-runner is executed as non-root,
+   - `~/.gitlab-runner/certs/hostname.crt` on *nix systems when gitlab-runner is executed as non-root.
    - `./certs/hostname.crt` on other systems.
 
    If the address of your server is: `https://my.gitlab.server.com:8443/`.

docs/development/README.md

@@ -150,7 +150,7 @@ To execute the tests run:
 make test
 ```
 
-## 9. Congratulations!
+## 9. Contribute
 
 You can start hacking GitLab-Runner code. If you are interested you can use Intellij IDEA Community Edition with [go-lang-idea-plugin](https://github.com/go-lang-plugin-org/go-lang-idea-plugin) to edit and debug code.
 

docs/executors/README.md

@@ -31,7 +31,7 @@ you decide which executor to use.
 | Executor                                          | SSH  | Shell   | VirtualBox | Parallels | Docker | Kubernetes | Custom         |
 |:--------------------------------------------------|:----:|:-------:|:----------:|:---------:|:------:|:----------:|---------------:|
 | Clean build environment for every build           | ✗    | ✗       | ✓          | ✓         | ✓      | ✓          |conditional (4) |
-| Reuse previous clone if it exists                 | ✓    | ✓       |            | ✗         | ✓      | ✗          |conditional (4) |
+| Reuse previous clone if it exists                 | ✓    | ✓       | ✗          | ✗         | ✓      | ✗          |conditional (4) |
 | Migrate runner machine                            | ✗    | ✗       | partial    | partial   | ✓      | ✓          |✓               |
 | Zero-configuration support for concurrent builds  | ✗    | ✗ (1)   | ✓          | ✓         | ✓      | ✓          |conditional (4) |
 | Complicated build environments                    | ✗    | ✗ (2)   | ✓ (3)      | ✓ (3)     | ✓      | ✓          |✓               |

docs/executors/docker.md

@@ -165,6 +165,12 @@ These are defined with a colon (`:`) after the image name. For example, for
 Ruby you can see the supported tags at <https://hub.docker.com/_/ruby/>. If you
 don't specify a tag (like `image: ruby`), `latest` is implied.
 
+NOTE: **Note:**
+The image you choose to run your build in via `image` directive must have a
+working shell in its operating system `PATH`. Supported shells are `sh` or
+`bash` for Linux, `cmd` or PowerShell for Windows. GitLab Runner cannot
+execute a command using the underlying OS system calls (like `exec`).
+
 ## The `services` keyword
 
 The `services` keyword defines just another Docker image that is run during