Add latest changes from gitlab-org/gitlab@master

1 files changed, 139 insertions, 0 deletions

diff --git a/doc/development/windows.md b/doc/development/windows.md
new file mode 100644
index 00000000000..b5309002222
--- /dev/null
+++ b/doc/development/windows.md
@@ -0,0 +1,139 @@
+---
+type: reference, howto
+---
+
+# Windows Development
+
+There are times in development where a Windows development machine is needed.
+This is a guide for how to get a Windows development virtual machine on Google Cloud Platform
+(GCP) with the same preinstalled tools as the GitLab shared Windows runners.
+
+## Why Windows in Google Cloud?
+
+Use of Microsoft Windows operating systems on company laptops is banned under GitLab's [Approved Operating Systems policy](https://about.gitlab.com/handbook/security/approved_os.html#windows).
+
+This can make it difficult to develop features for the Windows platforms. Using GCP will allow us to have a temporary Windows machine that can be removed once we're done with it.
+
+## Shared Windows runners
+
+You can use the shared Windows runners in the case that you don't need a full Windows development machine.
+The [GitLab 12.7 Release Post](https://about.gitlab.com/releases/2020/01/22/gitlab-12-7-released/#windows-shared-runners-on-gitlabcom-beta)
+and [Windows shared runner beta blog post](https://about.gitlab.com/blog/2020/01/21/windows-shared-runner-beta/#getting-started) both
+outline quite a bit of useful information.
+
+To use the shared Windows runners add the following `tags` to relevant jobs in your `.gitlab-ci.yml` file:
+
+```yaml
+tags:
+  - shared-windows
+  - windows
+  - windows-1809
+```
+
+A list of software preinstalled on the Windows images is available at: [Preinstalled software](https://gitlab.com/gitlab-org/ci-cd/shared-runners/images/gcp/windows-containers/blob/master/cookbooks/preinstalled-software/README.md).
+
+## GCP Windows image for development
+
+The [shared Windows GitLab
+runners](https://about.gitlab.com/releases/2020/01/22/gitlab-12-7-released/#windows-shared-runners-on-gitlabcom-beta)
+are built with [Packer](https://www.packer.io/).
+
+The Infrastructure as Code repository for building the Google Cloud images is available at:
+[GitLab Google Cloud Platform Shared Runner Images](https://gitlab.com/gitlab-org/ci-cd/shared-runners/images/gcp/windows-containers).
+
+### Build image
+
+There is a chance that your Google Cloud group may already have an image
+built. Search the available images before you do the work to build your
+own.
+
+Build a Google Cloud image with the above shared runners repo by doing the following:
+
+1. Install [Packer](https://www.packer.io/) (tested to work with version 1.5.1).
+1. Install Packer Windows Update Provisioner.
+   1. Clone the repository <https://github.com/rgl/packer-provisioner-windows-update> and `cd` into the cloned directory.
+   1. Run the command `go build -o packer-provisioner-windows-update` (requires `go` to be installed).
+   1. Verify `packer-provisioner-windows-update` is in the `PATH` environment variable.
+1. Add all [required environment variables](https://gitlab.com/gitlab-org/ci-cd/shared-runners/images/gcp/windows-containers/-/blob/master/packer.json#L2-10)
+   in the `packer.json` file to your environment (perhaps use [direnv](https://direnv.net/)).
+1. Build the image by running the command: `packer build packer.json`.
+
+## How to use a Windows image in GCP
+
+1. In a web browser, go to <https://console.cloud.google.com/compute/images>.
+1. Filter images by the name you used when creating image, `windows` is likely all you need to filter by.
+1. Click the image's name.
+1. Click the **CREATE INSTANCE** link.
+1. Important: Change name to what you'd like as you can't change it later.
+1. Optional: Change Region to be closest to you as well as any other option you'd like.
+1. Click **Create** at the bottom of the page.
+1. Click the name of your newly created VM Instance (optionally you can filter to find it).
+1. Click **Set Windows password**.
+1. Optional: Set a username or use default.
+1. Click **Next**.
+1. Copy and save the password as it won't be shown again.
+1. Click **RDP** down arrow.
+1. Click **Download the RDP file**.
+1. Open the downloaded RDP file with the Windows remote desktop app (<https://docs.microsoft.com/en-us/windows-server/remote/remote-desktop-services/clients/remote-desktop-clients>).
+1. Click **Continue** to accept the certificate.
+1. Enter the password and click **Next**.
+
+You should now be remoted into a Windows machine with a command prompt.
+
+### Optional: Use GCP VM Instance as a runner
+
+- Register the runner with a project: `gitlab-runner.exe register`.
+- Install the runner:`gitlab-runner.exe install`.
+- Start the runner: `gitlab-runner.exe start`.
+
+For more information, see [Install GitLab Runner on Windows](https://docs.gitlab.com/runner/install/windows.html)
+and [Registering Runners](https://docs.gitlab.com/runner/register/index.html).
+
+## Developer tips
+
+Here are a few tips on GCP and Windows.
+
+### GCP cost savings
+
+To minimise the cost of your GCP VM instance, stop it when you're not using it.
+If you do, you'll need to redownload the RDP file from the console as the IP
+address changes every time you stop and start it.
+
+### chocolatey
+
+Chocolatey is a package manager for Windows. You can search for packages on <https://chocolatey.org/>.
+
+- `choco install vim`
+
+### Visual Studio (install / usage for full GUI)
+
+You can install Visual Studio and run it within the Windows Remote Desktop app.
+
+Install it by running: `choco install visualstudio2019community`
+
+Start it by running: `"C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\Common7\IDE\devenv.exe" .`
+
+### .NET 3 support
+
+You can install .NET version 3 support with the following `DISM` command:
+
+`DISM /Online /Enable-Feature /FeatureName:NetFx3 /All`
+
+### nix -> Windows cmd tips
+
+The first tip for using the Windows command shell is to open Powershell and use that instead.
+
+Start Powershell: `start powershell`.
+
+Powershell has aliases for all of the following commands so you don't have to learn the native commands:
+
+- `ls` ---> `dir`
+- `rm` ---> `del`
+- `rm -rf nonemptydir` ---> `rmdir /S nonemptydir`
+- `/` ---> `\` (path separator)
+- `cat` ---> `type`
+- `mv` ---> `move`
+- Redirection works the same (i.e. `>` and `2>&1`)
+- `.\some.exe` to call a local executable
+- curl is available
+- `..` and `.` are available