Adding --check to run a serials network test against GitHub or GHES. (#900)

* add --check.

docs/checks/actions.md

@@ -0,0 +1,44 @@
+
+# Actions Connection Check
+
+## What is this check for?
+
+Make sure the runner has access to actions service for GitHub.com or GitHub Enterprise Server
+
+- For GitHub.com
+  - The runner needs to access https://api.github.com for downloading actions.
+  - The runner needs to access https://vstoken.actions.githubusercontent.com/_apis/.../ for requesting an access token.
+  - The runner needs to access https://pipelines.actions.githubusercontent.com/_apis/.../ for receiving workflow jobs.
+- For GitHub Enterprise Server
+  - The runner needs to access https://myGHES.com/api/v3 for downloading actions.
+  - The runner needs to access https://myGHES.com/_services/vstoken/_apis/.../ for requesting an access token.
+  - The runner needs to access https://myGHES.com/_services/pipelines/_apis/.../ for receiving workflow jobs.
+
+## What is checked?
+
+- DNS lookup for api.github.com or myGHES.com using dotnet
+- Ping api.github.com or myGHES.com using dotnet
+- Make HTTP GET to https://api.github.com or https://myGHES.com/api/v3 using dotnet, check response headers contains `X-GitHub-Request-Id` 
+---
+- DNS lookup for vstoken.actions.githubusercontent.com using dotnet
+- Ping vstoken.actions.githubusercontent.com using dotnet
+- Make HTTP GET to https://vstoken.actions.githubusercontent.com/_apis/health or https://myGHES.com/_services/vstoken/_apis/health using dotnet, check response headers contains `x-vss-e2eid` 
+---
+- DNS lookup for pipelines.actions.githubusercontent.com using dotnet
+- Ping pipelines.actions.githubusercontent.com using dotnet
+- Make HTTP GET to https://pipelines.actions.githubusercontent.com/_apis/health or https://myGHES.com/_services/pipelines/_apis/health using dotnet, check response headers contains `x-vss-e2eid` 
+
+## How to fix the issue?
+
+### 1. Check the common network issue
+  
+  > Please check the [network doc](./network.md)
+
+### 2. SSL certificate related issue
+
+  If you are seeing `System.Net.Http.HttpRequestException: The SSL connection could not be established, see inner exception.` in the log, it means the runner can't connect to Actions service due to SSL handshake failure.
+  > Please check the [SSL cert doc](./sslcert.md)
+  
+## Still not working?
+
+Contact GitHub customer service or log an issue at https://github.com/actions/runner if you think it's a runner issue.

docs/checks/git.md

@@ -0,0 +1,34 @@
+# Git Connection Check
+
+## What is this check for?
+
+Make sure `git` can access GitHub.com or your GitHub Enterprise Server.
+
+
+## What is checked?
+
+The test is done by executing
+```bash
+# For GitHub.com
+git ls-remote --exit-code https://github.com/actions/checkout HEAD
+
+# For GitHub Enterprise Server
+git ls-remote --exit-code https://ghes.me/actions/checkout HEAD
+```
+
+The test also set environment variable `GIT_TRACE=1` and `GIT_CURL_VERBOSE=1` before running `git ls-remote`, this will make `git` to produce debug log for better debug any potential issues.
+
+## How to fix the issue?
+
+### 1. Check the common network issue
+  
+    > Please check the [network doc](./network.md)
+
+### 2. SSL certificate related issue
+
+  If you are seeing `SSL Certificate problem:` in the log, it means the `git` can't connect to the GitHub server due to SSL handshake failure.
+  > Please check the [SSL cert doc](./sslcert.md)
+  
+## Still not working?
+
+Contact GitHub customer service or log an issue at https://github.com/actions/runner if you think it's a runner issue.

docs/checks/internet.md

@@ -0,0 +1,26 @@
+# Internet Connection Check
+
+## What is this check for?
+
+Make sure the runner has access to https://api.github.com
+
+The runner needs to access https://api.github.com to download any actions from the marketplace.
+
+Even the runner is configured to GitHub Enterprise Server, the runner can still download actions from GitHub.com with [GitHub Connect](https://docs.github.com/en/enterprise-server@2.22/admin/github-actions/enabling-automatic-access-to-githubcom-actions-using-github-connect)
+
+
+## What is checked?
+
+- DNS lookup for api.github.com using dotnet
+- Ping api.github.com using dotnet
+- Make HTTP GET to https://api.github.com using dotnet, check response headers contains `X-GitHub-Request-Id` 
+
+## How to fix the issue?
+
+### 1. Check the common network issue
+  
+  > Please check the [network doc](./network.md)
+
+## Still not working?
+
+Contact GitHub customer service or log an issue at https://github.com/actions/runner if you think it's a runner issue.

docs/checks/network.md

@@ -0,0 +1,29 @@
+## Common Network Related Issues
+
+### Common things that can cause the runner to not working properly
+
+- Bug in the runner or the dotnet framework that causes actions runner can't make Http request in a certain network environment.
+
+- Proxy/Firewall block certain HTTP method, like it block all POST and PUT calls which the runner will use to upload logs.
+
+- Proxy/Firewall only allows requests with certain user-agent to pass through and the actions runner user-agent is not in the allow list.
+
+- Proxy try to decrypt and exam HTTPS traffic for security purpose but cause the actions-runner to fail to finish SSL handshake due to the lack of trusting proxy's CA.
+
+- Firewall rules that block action runner from accessing certain hosts, ex: `*.github.com`, `*.actions.githubusercontent.com`, etc.
+
+
+### Identify and solve these problems
+
+The key is to figure out where is the problem, the network environment, or the actions runner?
+
+Use a 3rd party tool to make the same requests as the runner did would be a good start point.
+
+- Use `nslookup` to check DNS
+- Use `ping` to check Ping
+- Use `curl -v` to check the network stack, good for verifying default certificate/proxy settings.
+- Use `Invoke-WebRequest` from `pwsh` (`PowerShell Core`) to check the dotnet network stack, good for verifying bugs in the dotnet framework.
+
+If the 3rd party tool is also experiencing the same error as the runner does, then you might want to contact your network administrator for help.
+
+Otherwise, contact GitHub customer support or log an issue at https://github.com/actions/runner

docs/checks/nodejs.md

@@ -0,0 +1,30 @@
+# Node.js Connection Check
+
+## What is this check for?
+
+Make sure the built-in node.js has access to GitHub.com or GitHub Enterprise Server.
+
+The runner carries it's own copy of node.js executable under `<runner_root>/externals/node12/`.
+
+All javascript base Actions will get executed by the built-in `node` at `<runner_root>/externals/node12/`.
+
+> Not the `node` from `$PATH`
+
+## What is checked?
+
+- Make HTTPS GET to https://api.github.com or https://myGHES.com/api/v3 using node.js, make sure it gets 200 response code.
+
+## How to fix the issue?
+
+### 1. Check the common network issue
+  
+  > Please check the [network doc](./network.md)
+
+### 2. SSL certificate related issue
+
+  If you are seeing `Https request failed due to SSL cert issue` in the log, it means the `node.js` can't connect to the GitHub server due to SSL handshake failure.
+  > Please check the [SSL cert doc](./sslcert.md)
+  
+## Still not working?
+
+Contact GitHub customer service or log an issue at https://github.com/actions/runner if you think it's a runner issue.

docs/checks/sslcert.md

@@ -0,0 +1,89 @@
+## SSL Certificate Related Issues
+
+You might run into an SSL certificate error when your GitHub Enterprise Server is using a self-signed SSL server certificate or a web proxy within your network is decrypting HTTPS traffic for a security audit.
+
+As long as your certificate is generated properly, most of the issues should be fixed after your trust the certificate properly on the runner machine.
+
+> Different OS might have extra requirements on SSL certificate,
+> Ex: macOS requires `ExtendedKeyUsage` https://support.apple.com/en-us/HT210176
+
+### Don't skip SSL cert validation
+
+> !!! DO NOT SKIP SSL CERT VALIDATION !!!  
+> !!! IT IS A BAD SECURITY PRACTICE !!!  
+
+### Download SSL certificate chain 
+
+Depends on how your SSL server certificate gets configured, you might need to download the whole certificate chain from a machine that has trusted the SSL certificate's CA.
+
+- Approach 1: Download certificate chain using a browser (Chrome, Firefox, IT), you can google for more example, [here is what I found](https://medium.com/@menakajain/export-download-ssl-certificate-from-server-site-url-bcfc41ea46a2)
+
+- Approach 2: Download certificate chain using OpenSSL, you can google for more example, [here is what I found](https://superuser.com/a/176721)
+
+- Approach 3: Ask your network administrator or the owner of the CA certificate to send you a copy of it
+
+### Trust CA certificate for the Runner
+
+The actions runner is a dotnet core application which will follow how dotnet load SSL CA certificates on each OS.
+
+You can get full details documentation at [here](https://docs.microsoft.com/en-us/dotnet/standard/security/cross-platform-cryptography#x509store)
+
+In short: 
+- Windows: Load from Windows certificate store.
+- Linux: Load from OpenSSL CA cert bundle.
+- macOS: Load from macOS KeyChain.
+
+To let the runner trusts your CA certificate, you will need to:
+1. Save your SSL certificate chain which includes the root CA and all intermediate CAs into a `.pem` file.
+2. Use `OpenSSL` to convert `.pem` file to a proper format for different OS, here is some [doc with sample commands](https://www.sslshopper.com/ssl-converter.html)
+3. Trust CA on different OS:
+    - Windows: https://docs.microsoft.com/en-us/skype-sdk/sdn/articles/installing-the-trusted-root-certificate
+    - macOS: ![trust ca cert](./../res/macOStrustCA.gif)
+    - Linux: Refer to the distribution documentation
+      1. RedHat: https://www.redhat.com/sysadmin/ca-certificates-cli
+      2. Ubuntu: http://manpages.ubuntu.com/manpages/focal/man8/update-ca-certificates.8.html
+      3. Google search: "trust ca certificate on [linux distribution]"
+      4. If all approaches failed, set environment variable `SSL_CERT_FILE` to the CA bundle `.pem` file we get. 
+    > To verity cert gets installed properly on Linux, you can try use `curl -v https://sitewithsslissue.com` and `pwsh -Command \"Invoke-WebRequest -Uri https://sitewithsslissue.com\"`
+
+### Trust CA certificate for Git CLI
+
+Git uses various CA bundle file depends on your operation system.
+- Git packaged the CA bundle file within the Git installation on Windows 
+- Git use OpenSSL certificate CA bundle file on Linux and macOS
+
+You can check where Git check CA file by running:
+```bash
+export GIT_CURL_VERBOSE=1
+git ls-remote https://github.com/actions/runner HEAD
+```
+
+You should see something like:
+```
+* Couldn't find host github.com in the .netrc file; using defaults
+*   Trying 140.82.114.4...
+* TCP_NODELAY set
+* Connected to github.com (140.82.114.4) port 443 (#0)
+* ALPN, offering h2
+* ALPN, offering http/1.1
+* successfully set certificate verify locations:
+*   CAfile: /etc/ssl/cert.pem
+  CApath: none
+* SSL connection using TLSv1.2 / ECDHE-RSA-AES128-GCM-SHA256
+```
+This tells me `/etc/ssl/cert.pem` is where it read trusted CA certificates.
+
+To let Git trusts your CA certificate, you will need to:
+1. Save your SSL certificate chain which includes the root CA and all intermediate CAs into a `.pem` file.
+2. Set `http.sslCAInfo` Git config or `GIT_SSL_CAINFO` environment variable to the full path of the `.pem` file [Git Doc](https://git-scm.com/docs/git-config#Documentation/git-config.txt-httpsslCAInfo)
+> I would recommend using `http.sslCAInfo` since it can be scope to certain hosts that need the extra trusted CA.  
+> Ex: `git config --global http.https://myghes.com/.sslCAInfo /extra/ca/cert.pem`  
+> This will make Git use the `/extra/ca/cert.pem` only when communicates with `https://myghes.com` and keep using the default CA bundle with others.
+
+### Trust CA certificate for Node.js
+
+Node.js has compiled a snapshot of the Mozilla CA store that is fixed at each version of Node.js' release time.
+
+To let Node.js trusts your CA certificate, you will need to:
+1. Save your SSL certificate chain which includes the root CA and all intermediate CAs into a `.pem` file.
+2. Set environment variable `NODE_EXTRA_CA_CERTS` which point to the file. ex: `export NODE_EXTRA_CA_CERTS=/full/path/to/cacert.pem` or `set NODE_EXTRA_CA_CERTS=C:\full\path\to\cacert.pem`