gitlab-org--gitlab-foss/doc/development/windows.md

---
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 repository 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 re-download 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