docs: Document using labels with self-hosted runners (#3508)

Explanation of issue: There are many popular CI systems that exist out
in the world, not only GitHub Actions. It's probably common enough that
a developer comes to this project and needs to configure the Terraform
runners with GitHub Actions, while also having in their mind how other
systems operate, and those may be different. It's easy to imagine all
runner labels must match all job labels. Other systems are designed that
way. To quickly solve the problem this is a sort of cheatsheet.

Author: sdarwin

README.md

@@ -55,7 +55,7 @@ A logical question would be, why not Kubernetes? In the current approach, we sta
 
 ## Overview
 
-The moment a GitHub action workflow requiring a `self-hosted` runner is triggered, GitHub will try to find a runner which can execute the workload. This module reacts to GitHub's [`workflow_job` event](https://docs.github.com/en/free-pro-team@latest/developers/webhooks-and-events/webhook-events-and-payloads#workflow_job) for the triggered workflow and creates a new runner if necessary.
+The moment a GitHub action workflow requiring a `self-hosted` runner is triggered, GitHub will try to find a runner which can execute the workload. See [additional notes](docs/additional_notes.md) for how the selection is made. This module reacts to GitHub's [`workflow_job` event](https://docs.github.com/en/free-pro-team@latest/developers/webhooks-and-events/webhook-events-and-payloads#workflow_job) for the triggered workflow and creates a new runner if necessary.
 
 For receiving the `workflow_job` event by the webhook (lambda), a webhook needs to be created in GitHub. The `check_run` option was dropped from version 2.x. The following options to send the event are supported.
 

docs/additional_notes.md

@@ -0,0 +1,34 @@
+
+# Runner Labels
+
+Some CI systems require that all labels match between a job and a runner. In the case of GitHub Actions, workflows will be assigned to runners which have all the labels requested by the workflow, however it is not necessary the workflow mentions all labels.
+
+Labels specify the capabilities the runners have. The labels in the workflow are the capabilities needed. If the capabilities requested by the workflow are provided by the runners, there is match.  
+
+Examples:
+
+| Runner Labels | Workflow runs-on: | Result |
+| ------------- | ------------- | ------------- |
+| 'self-hosted', 'Linux', 'X64' | self-hosted | matches |
+| 'self-hosted', 'Linux', 'X64' | Linux | matches |
+| 'self-hosted', 'Linux', 'X64' | X64 | matches |
+| 'self-hosted', 'Linux', 'X64' | [ self-hosted, Linux ] | matches |
+| 'self-hosted', 'Linux', 'X64' | [ self-hosted, X64 ] | matches |
+| 'self-hosted', 'Linux', 'X64' | [ self-hosted, Linux, X64 ] | matches |
+| 'self-hosted', 'Linux', 'X64' | other1 | no match |
+| 'self-hosted', 'Linux', 'X64' | [ self-hosted, other2 ] | no match |
+| 'self-hosted', 'Linux', 'X64' | [ self-hosted, Linux, X64, other2 ] | no match |
+| 'self-hosted', 'Linux', 'X64', 'custom3' | custom3 | matches |
+| 'self-hosted', 'Linux', 'X64', 'custom3' | [ custom3, Linux ] | matches |
+| 'self-hosted', 'Linux', 'X64', 'custom3' | [ custom3, X64 ] | matches |
+| 'self-hosted', 'Linux', 'X64', 'custom3' | [ custom3, other7 ] | no match |
+
+If default labels are removed:
+
+| Runner Labels | Workflow runs-on: | Result |
+| ------------- | ------------- | ------------- |
+| 'custom5' | custom5 | matches |
+| 'custom5' | self-hosted | no match |
+| 'custom5' | Linux | no match |
+| 'custom5' | [ self-hosted, Linux ] | no match |
+| 'custom5' | [ custom5, self-hosted, Linux ] | no match |