Merge pull request #109 from guitarrapc/doc/readme

doc: update README
guitarrapc · Sep 21, 2023 · 814c74b · 814c74b
2 parents 9bd0bf7 + 89c456a
commit 814c74b
Show file tree

Hide file tree

Showing 9 changed files with 217 additions and 190 deletions.
diff --git a/.github/workflows/aws_oidc_credential_bug.yaml b/.github/workflows/aws_oidc_credential_bug.yaml
diff --git a/.github/workflows/workflow_telemetry.yaml b/.github/workflows/workflow_telemetry.yaml
@@ -14,6 +14,8 @@ jobs:
     steps:
       - name: Collect Workflow Telemetry
         uses: runforesight/workflow-telemetry-action@v1
+        with:
+          theme: dark # or light. dark generate charts compatible with Github dark mode.
       - uses: actions/checkout@v4
       - uses: actions/setup-dotnet@v3
         with:

diff --git a/README.md b/README.md
@@ -65,11 +65,12 @@ GitHub Actions research and test laboratory.
 - [Basic - BAD PATTERN](#basic---bad-pattern)
   - [Env refer env](#env-refer-env)
 - [Advanced](#advanced)
-  - [Checkout faster with git sparse-checkout](#checkout-faster-with-git-sparse-checkout)
+  - [Checkout faster with Git sparse-checkout](#checkout-faster-with-git-sparse-checkout)
   - [Dispatch other repo workflow](#dispatch-other-repo-workflow)
   - [Fork user workflow change prevention](#fork-user-workflow-change-prevention)
   - [Lint GitHub Actions workflow itself](#lint-github-actions-workflow-itself)
   - [PR info from Merge Commit](#pr-info-from-merge-commit)
+  - [Telemetry for GitHub Workflow execution](#telemetry-for-github-workflow-execution)
 - [Cheat Sheet](#cheat-sheet)
   - [Actions naming](#actions-naming)
   - [Get Branch](#get-branch)
@@ -324,7 +325,7 @@ GitHub Actions support checkout by actions and supports variety of checkout opti
 ## Dump context metadata
 
 Use Context to retrive job id, name and others system info.
-Make sure you can not refer github context in script.
+Make sure you can not refer `gitHub` context in script.
 
 > see: [Context and expression syntax for GitHub Actions \- GitHub Help](https://help.github.com/en/actions/reference/context-and-expression-syntax-for-github-actions#github-context)
 
@@ -866,7 +867,7 @@ jobs:
 
 To reuse local job, create local node action is another way to do, this is calls `node actions`.
 Create yaml file inside local action path, then declare `using: "node12"` in local action.yaml.
-Next place your node.js source files inside actions directory, you may require `index.js` for entrypoint.
+Next place your Node.js source files inside actions directory, you may require `index.js` for entrypoint.
 
 > TIPS: You may find it is useful when you are running on GHE and copy GitHub Actions to your local.
 
@@ -1415,7 +1416,7 @@ jobs:
 
 ## Workflow dispatch and passing input
 
-GitHub Actions offer `workflow_dispatch` event to execute workflow manually from WebUI.
+GitHub Actions offer `workflow_dispatch` event to execute workflow manually from Web UI.
 Also you can use [action inputs](https://docs.github.com/en/actions/creating-actions/metadata-syntax-for-github-actions#inputs) to specify value trigger on manual trigger.
 
 ```yaml
@@ -1594,7 +1595,7 @@ jobs:
 
 ## Detect file changed
 
-you can handle commit file handle with github actions [trilom/file/-changes/-action](https://github.com/trilom/file-changes-action).
+you can handle commit file handle with GitHub actions [trilom/file/-changes/-action](https://github.com/trilom/file-changes-action).
 
 ```yaml
 # .github/workflows/pr_path_changed.yaml
@@ -1958,7 +1959,7 @@ jobs:
 
 Advanced tips.
 
-## Checkout faster with git sparse-checkout
+## Checkout faster with Git sparse-checkout
 
 [actions/checkout](https://github.com/actions) supports both [shallow-clone](https://git-scm.com/docs/shallow) and [sparse checkout](https://git-scm.com/docs/git-sparse-checkout) which is quite useful for monorepository. Typically, monorepository contains many folders and files, but you may want to checkout only specific folder or files.
 
@@ -1971,15 +1972,15 @@ Let's see what is difference between `shallow-clone` and `sparse-checkout`.
 
 **Shallow clone**
 
-Shallow clones use the `--depth=<N>` parameter in git clone to truncate the commit history. Typically, --depth=1 signifies that we only care about the most recent commits. This drastically reduces the amount of data that needs to be fetched, leading to faster clones and less storage of shallow history.
+Shallow clones use the `--depth=<N>` parameter in `git clone` to truncate the commit history. Typically, --depth=1 signifies that we only care about the most recent commits. This drastically reduces the amount of data that needs to be fetched, leading to faster clones and less storage of shallow history.
 
 ![](https://github.blog/jp/wp-content/uploads/sites/2/2021/01/Image4.png?w=800&resize=800%2C414)
 
 > ref: https://github.blog/2020-12-21-get-up-to-speed-with-partial-clone-and-shallow-clone/
 
 **Sparse checkout**
 
-Sparse checkout use the `git sparse-checkout set <PATH>` before git clone to truncate the checkout files and folders. This amazingly reduces the amount of data that needs to be fetched, leading to faster checkout and less storage of limited paths.
+Sparse checkout use the `git sparse-checkout set <PATH>` before `git clone` to truncate the checkout files and folders. This amazingly reduces the amount of data that needs to be fetched, leading to faster checkout and less storage of limited paths.
 
 ![](https://i0.wp.com/user-images.githubusercontent.com/121322/72286599-50af8e00-35fa-11ea-9025-d7cbb730192c.png?ssl=1)
 
@@ -2397,7 +2398,7 @@ jobs:
 
 You have two choice.
 
-1. Use git cli. Retrieve 1st and 3rd line of merge commit.
+1. Use Git cli. Retrieve 1st and 3rd line of merge commit.
 2. Use some action to retrieve PR info from merge commit.
 
 Below use [jwalton/gh-find-current-pr](https://github.com/jwalton/gh-find-current-pr) to retrieve PR info from merge commit.
@@ -2428,6 +2429,54 @@ jobs:
           PR_TITLE: ${{ steps.pr.outputs.title }}
 ```
 
+
+## Telemetry for GitHub Workflow execution
+
+GitHub Actions [runforesight/workflow-telemetry-action](https://github.com/runforesight/workflow-telemetry-action) offers workflow telemetry. Telemetry indicate which step consume much Execution Time, CPU, Memory and Network I/O. Default settings post telemetry result to PR comment and JOB Summary.
+
+
+To enable telemetry, set `runforesight/workflow-telemetry-action@v1` on the first step of your job, then action collect telemetry for later steps.
+
+```yaml
+# .github/workflows/workflow_telemetry.yaml
+
+name: workflow telemetry
+# run on both branch push and tag push
+on:
+  workflow_dispatch:
+  push:
+    branches: ["main"]
+  pull_request:
+    branches: ["main"]
+
+jobs:
+  dotnet-console:
+    runs-on: ubuntu-latest
+    timeout-minutes: 3
+    steps:
+      - name: Collect Workflow Telemetry
+        uses: runforesight/workflow-telemetry-action@v1
+        with:
+          theme: dark # or light. dark generate charts compatible with Github dark mode.
+      - uses: actions/checkout@v4
+      - uses: actions/setup-dotnet@v3
+        with:
+          dotnet-version: 6.0.x
+      - name: dotnet build
+        run: dotnet build ./src/dotnet/console/ -c Debug
+      - name: dotnet test
+        run: dotnet test ./src/dotnet/console-tests/ -c Debug --logger GitHubActions
+      - name: dotnet publish
+        run: dotnet publish ./src/dotnet/console/ -c Debug -o ./out/dotnet-console
+
+```
+
+Here's telemetry posted to [PR comment](https://github.com/guitarrapc/githubactions-lab/pull/109).
+
+![image](https://github.com/guitarrapc/githubactions-lab/assets/3856350/c1194994-a3ef-4ccb-a4d4-9a0e1bf287fd)
+
+You can find same telemetry result on [Job Summary](https://github.com/guitarrapc/githubactions-lab/actions/runs/6266182534), either.
+
 # Cheat Sheet
 
 GitHub Actions cheet sheet.
@@ -2501,7 +2550,7 @@ ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id
 
 ## GitHub Actions commit icon
 
-Use following git config to commit as GitHub Actions icon.
+Use following Git config to commit as GitHub Actions icon.
 
 ```bash
 git config user.name github-actions[bot]

diff --git a/contexts/export/pull_request_opened.sh b/contexts/export/pull_request_opened.sh
@@ -30,16 +30,16 @@ declare -x GITHUB_ACTOR="guitarrapc"
 declare -x GITHUB_ACTOR_ID="3856350"
 declare -x GITHUB_API_URL="https://api.github.com"
 declare -x GITHUB_BASE_REF="main"
-declare -x GITHUB_ENV="/home/runner/work/_temp/_runner_file_commands/set_env_5b121aff-e598-406d-a1ba-76cd0939e1de"
+declare -x GITHUB_ENV="/home/runner/work/_temp/_runner_file_commands/set_env_4950c8e3-bc1e-49ce-8bc4-84afedd1fc8f"
 declare -x GITHUB_EVENT_NAME="pull_request"
 declare -x GITHUB_EVENT_PATH="/home/runner/work/_temp/_github_workflow/event.json"
 declare -x GITHUB_GRAPHQL_URL="https://api.github.com/graphql"
-declare -x GITHUB_HEAD_REF="feature/workflow_telemetry"
+declare -x GITHUB_HEAD_REF="doc/readme"
 declare -x GITHUB_JOB="dump-context"
-declare -x GITHUB_OUTPUT="/home/runner/work/_temp/_runner_file_commands/set_output_5b121aff-e598-406d-a1ba-76cd0939e1de"
-declare -x GITHUB_PATH="/home/runner/work/_temp/_runner_file_commands/add_path_5b121aff-e598-406d-a1ba-76cd0939e1de"
-declare -x GITHUB_REF="refs/pull/108/merge"
-declare -x GITHUB_REF_NAME="108/merge"
+declare -x GITHUB_OUTPUT="/home/runner/work/_temp/_runner_file_commands/set_output_4950c8e3-bc1e-49ce-8bc4-84afedd1fc8f"
+declare -x GITHUB_PATH="/home/runner/work/_temp/_runner_file_commands/add_path_4950c8e3-bc1e-49ce-8bc4-84afedd1fc8f"
+declare -x GITHUB_REF="refs/pull/109/merge"
+declare -x GITHUB_REF_NAME="109/merge"
 declare -x GITHUB_REF_PROTECTED="false"
 declare -x GITHUB_REF_TYPE="branch"
 declare -x GITHUB_REPOSITORY="guitarrapc/githubactions-lab"
@@ -48,16 +48,16 @@ declare -x GITHUB_REPOSITORY_OWNER="guitarrapc"
 declare -x GITHUB_REPOSITORY_OWNER_ID="3856350"
 declare -x GITHUB_RETENTION_DAYS="90"
 declare -x GITHUB_RUN_ATTEMPT="1"
-declare -x GITHUB_RUN_ID="6265665654"
-declare -x GITHUB_RUN_NUMBER="169"
+declare -x GITHUB_RUN_ID="6266182719"
+declare -x GITHUB_RUN_NUMBER="172"
 declare -x GITHUB_SERVER_URL="https://github.com"
-declare -x GITHUB_SHA="013094c17440254d5b10c343da19aae5721fa51e"
-declare -x GITHUB_STATE="/home/runner/work/_temp/_runner_file_commands/save_state_5b121aff-e598-406d-a1ba-76cd0939e1de"
-declare -x GITHUB_STEP_SUMMARY="/home/runner/work/_temp/_runner_file_commands/step_summary_5b121aff-e598-406d-a1ba-76cd0939e1de"
+declare -x GITHUB_SHA="678d8a19b062b620a95c338eab22e7db3bd8c3a4"
+declare -x GITHUB_STATE="/home/runner/work/_temp/_runner_file_commands/save_state_4950c8e3-bc1e-49ce-8bc4-84afedd1fc8f"
+declare -x GITHUB_STEP_SUMMARY="/home/runner/work/_temp/_runner_file_commands/step_summary_4950c8e3-bc1e-49ce-8bc4-84afedd1fc8f"
 declare -x GITHUB_TRIGGERING_ACTOR="guitarrapc"
 declare -x GITHUB_WORKFLOW="auto dump context"
-declare -x GITHUB_WORKFLOW_REF="guitarrapc/githubactions-lab/.github/workflows/auto_dump_context.yaml@refs/pull/108/merge"
-declare -x GITHUB_WORKFLOW_SHA="013094c17440254d5b10c343da19aae5721fa51e"
+declare -x GITHUB_WORKFLOW_REF="guitarrapc/githubactions-lab/.github/workflows/auto_dump_context.yaml@refs/pull/109/merge"
+declare -x GITHUB_WORKFLOW_SHA="678d8a19b062b620a95c338eab22e7db3bd8c3a4"
 declare -x GITHUB_WORKSPACE="/home/runner/work/githubactions-lab/githubactions-lab"
 declare -x GOROOT_1_19_X64="/opt/hostedtoolcache/go/1.19.13/x64"
 declare -x GOROOT_1_20_X64="/opt/hostedtoolcache/go/1.20.8/x64"
@@ -66,14 +66,14 @@ declare -x GRADLE_HOME="/usr/share/gradle-8.3"
 declare -x HOME="/home/runner"
 declare -x HOMEBREW_CLEANUP_PERIODIC_FULL_DAYS="3650"
 declare -x HOMEBREW_NO_AUTO_UPDATE="1"
-declare -x INVOCATION_ID="6309ac5a2ad64dfdb91201a62a3dec55"
+declare -x INVOCATION_ID="d4e28ec5af0e418188ddf0f214c0e7e3"
 declare -x ImageOS="ubuntu22"
 declare -x ImageVersion="20230917.1.0"
 declare -x JAVA_HOME="/usr/lib/jvm/temurin-11-jdk-amd64"
 declare -x JAVA_HOME_11_X64="/usr/lib/jvm/temurin-11-jdk-amd64"
 declare -x JAVA_HOME_17_X64="/usr/lib/jvm/temurin-17-jdk-amd64"
 declare -x JAVA_HOME_8_X64="/usr/lib/jvm/temurin-8-jdk-amd64"
-declare -x JOURNAL_STREAM="8:17007"
+declare -x JOURNAL_STREAM="8:17670"
 declare -x LANG="C.UTF-8"
 declare -x LEIN_HOME="/usr/local/lib/lein"
 declare -x LEIN_JAR="/usr/local/lib/lein/self-installs/leiningen-2.10.0-standalone.jar"
@@ -88,12 +88,12 @@ declare -x POWERSHELL_DISTRIBUTION_CHANNEL="GitHub-Actions-ubuntu22"
 declare -x PWD="/home/runner/work/githubactions-lab/githubactions-lab"
 declare -x RUNNER_ARCH="X64"
 declare -x RUNNER_ENVIRONMENT="github-hosted"
-declare -x RUNNER_NAME="GitHub Actions 40"
+declare -x RUNNER_NAME="GitHub Actions 2"
 declare -x RUNNER_OS="Linux"
 declare -x RUNNER_PERFLOG="/home/runner/perflog"
 declare -x RUNNER_TEMP="/home/runner/work/_temp"
 declare -x RUNNER_TOOL_CACHE="/opt/hostedtoolcache"
-declare -x RUNNER_TRACKING_ID="github_39951c9f-b292-4fc2-ac7e-b8e3e5b16503"
+declare -x RUNNER_TRACKING_ID="github_a783cfe0-8c13-4725-aac7-b6e6109fe993"
 declare -x RUNNER_USER="runner"
 declare -x RUNNER_WORKSPACE="/home/runner/work/githubactions-lab"
 declare -x SELENIUM_JAR_PATH="/usr/share/java/selenium-server.jar"
@@ -109,7 +109,7 @@ declare -x STATS_UE="true"
 declare -x STATS_V3PS="true"
 declare -x STATS_VMD="true"
 declare -x SWIFT_PATH="/usr/share/swift/usr/bin"
-declare -x SYSTEMD_EXEC_PID="572"
+declare -x SYSTEMD_EXEC_PID="582"
 declare -x USER="runner"
 declare -x VCPKG_INSTALLATION_ROOT="/usr/local/share/vcpkg"
 declare -x XDG_CONFIG_HOME="/home/runner/.config"

diff --git a/contexts/export/pull_request_synchronize.sh b/contexts/export/pull_request_synchronize.sh
@@ -30,16 +30,16 @@ declare -x GITHUB_ACTOR="guitarrapc"
 declare -x GITHUB_ACTOR_ID="3856350"
 declare -x GITHUB_API_URL="https://api.github.com"
 declare -x GITHUB_BASE_REF="main"
-declare -x GITHUB_ENV="/home/runner/work/_temp/_runner_file_commands/set_env_0983140a-d58a-44cc-a7a4-8839eae80a99"
+declare -x GITHUB_ENV="/home/runner/work/_temp/_runner_file_commands/set_env_d2036ab8-b068-4e88-a9de-c76fd2e6a4c2"
 declare -x GITHUB_EVENT_NAME="pull_request"
 declare -x GITHUB_EVENT_PATH="/home/runner/work/_temp/_github_workflow/event.json"
 declare -x GITHUB_GRAPHQL_URL="https://api.github.com/graphql"
-declare -x GITHUB_HEAD_REF="feature/upload"
+declare -x GITHUB_HEAD_REF="doc/readme"
 declare -x GITHUB_JOB="dump-context"
-declare -x GITHUB_OUTPUT="/home/runner/work/_temp/_runner_file_commands/set_output_0983140a-d58a-44cc-a7a4-8839eae80a99"
-declare -x GITHUB_PATH="/home/runner/work/_temp/_runner_file_commands/add_path_0983140a-d58a-44cc-a7a4-8839eae80a99"
-declare -x GITHUB_REF="refs/pull/107/merge"
-declare -x GITHUB_REF_NAME="107/merge"
+declare -x GITHUB_OUTPUT="/home/runner/work/_temp/_runner_file_commands/set_output_d2036ab8-b068-4e88-a9de-c76fd2e6a4c2"
+declare -x GITHUB_PATH="/home/runner/work/_temp/_runner_file_commands/add_path_d2036ab8-b068-4e88-a9de-c76fd2e6a4c2"
+declare -x GITHUB_REF="refs/pull/109/merge"
+declare -x GITHUB_REF_NAME="109/merge"
 declare -x GITHUB_REF_PROTECTED="false"
 declare -x GITHUB_REF_TYPE="branch"
 declare -x GITHUB_REPOSITORY="guitarrapc/githubactions-lab"
@@ -48,16 +48,16 @@ declare -x GITHUB_REPOSITORY_OWNER="guitarrapc"
 declare -x GITHUB_REPOSITORY_OWNER_ID="3856350"
 declare -x GITHUB_RETENTION_DAYS="90"
 declare -x GITHUB_RUN_ATTEMPT="1"
-declare -x GITHUB_RUN_ID="6265633483"
-declare -x GITHUB_RUN_NUMBER="166"
+declare -x GITHUB_RUN_ID="6266227777"
+declare -x GITHUB_RUN_NUMBER="174"
 declare -x GITHUB_SERVER_URL="https://github.com"
-declare -x GITHUB_SHA="12e969181f9c0c7808fa0284f15c2c1f135739da"
-declare -x GITHUB_STATE="/home/runner/work/_temp/_runner_file_commands/save_state_0983140a-d58a-44cc-a7a4-8839eae80a99"
-declare -x GITHUB_STEP_SUMMARY="/home/runner/work/_temp/_runner_file_commands/step_summary_0983140a-d58a-44cc-a7a4-8839eae80a99"
+declare -x GITHUB_SHA="7bd369a33a5ba8124651418de5dc1091960102df"
+declare -x GITHUB_STATE="/home/runner/work/_temp/_runner_file_commands/save_state_d2036ab8-b068-4e88-a9de-c76fd2e6a4c2"
+declare -x GITHUB_STEP_SUMMARY="/home/runner/work/_temp/_runner_file_commands/step_summary_d2036ab8-b068-4e88-a9de-c76fd2e6a4c2"
 declare -x GITHUB_TRIGGERING_ACTOR="guitarrapc"
 declare -x GITHUB_WORKFLOW="auto dump context"
-declare -x GITHUB_WORKFLOW_REF="guitarrapc/githubactions-lab/.github/workflows/auto_dump_context.yaml@refs/pull/107/merge"
-declare -x GITHUB_WORKFLOW_SHA="12e969181f9c0c7808fa0284f15c2c1f135739da"
+declare -x GITHUB_WORKFLOW_REF="guitarrapc/githubactions-lab/.github/workflows/auto_dump_context.yaml@refs/pull/109/merge"
+declare -x GITHUB_WORKFLOW_SHA="7bd369a33a5ba8124651418de5dc1091960102df"
 declare -x GITHUB_WORKSPACE="/home/runner/work/githubactions-lab/githubactions-lab"
 declare -x GOROOT_1_19_X64="/opt/hostedtoolcache/go/1.19.13/x64"
 declare -x GOROOT_1_20_X64="/opt/hostedtoolcache/go/1.20.8/x64"
@@ -66,14 +66,14 @@ declare -x GRADLE_HOME="/usr/share/gradle-8.3"
 declare -x HOME="/home/runner"
 declare -x HOMEBREW_CLEANUP_PERIODIC_FULL_DAYS="3650"
 declare -x HOMEBREW_NO_AUTO_UPDATE="1"
-declare -x INVOCATION_ID="7c3b96e1b0d74e978a56814d7d663d6a"
+declare -x INVOCATION_ID="9474db572a08493a84311e12764f9bc0"
 declare -x ImageOS="ubuntu22"
 declare -x ImageVersion="20230917.1.0"
 declare -x JAVA_HOME="/usr/lib/jvm/temurin-11-jdk-amd64"
 declare -x JAVA_HOME_11_X64="/usr/lib/jvm/temurin-11-jdk-amd64"
 declare -x JAVA_HOME_17_X64="/usr/lib/jvm/temurin-17-jdk-amd64"
 declare -x JAVA_HOME_8_X64="/usr/lib/jvm/temurin-8-jdk-amd64"
-declare -x JOURNAL_STREAM="8:18452"
+declare -x JOURNAL_STREAM="8:17878"
 declare -x LANG="C.UTF-8"
 declare -x LEIN_HOME="/usr/local/lib/lein"
 declare -x LEIN_JAR="/usr/local/lib/lein/self-installs/leiningen-2.10.0-standalone.jar"
@@ -88,12 +88,12 @@ declare -x POWERSHELL_DISTRIBUTION_CHANNEL="GitHub-Actions-ubuntu22"
 declare -x PWD="/home/runner/work/githubactions-lab/githubactions-lab"
 declare -x RUNNER_ARCH="X64"
 declare -x RUNNER_ENVIRONMENT="github-hosted"
-declare -x RUNNER_NAME="GitHub Actions 34"
+declare -x RUNNER_NAME="GitHub Actions 29"
 declare -x RUNNER_OS="Linux"
 declare -x RUNNER_PERFLOG="/home/runner/perflog"
 declare -x RUNNER_TEMP="/home/runner/work/_temp"
 declare -x RUNNER_TOOL_CACHE="/opt/hostedtoolcache"
-declare -x RUNNER_TRACKING_ID="github_4c0a11b2-6453-4f45-98bb-fbb158b0e63c"
+declare -x RUNNER_TRACKING_ID="github_8eac62ea-363c-4617-b53d-38d8d5b64fa3"
 declare -x RUNNER_USER="runner"
 declare -x RUNNER_WORKSPACE="/home/runner/work/githubactions-lab"
 declare -x SELENIUM_JAR_PATH="/usr/share/java/selenium-server.jar"
@@ -109,7 +109,7 @@ declare -x STATS_UE="true"
 declare -x STATS_V3PS="true"
 declare -x STATS_VMD="true"
 declare -x SWIFT_PATH="/usr/share/swift/usr/bin"
-declare -x SYSTEMD_EXEC_PID="570"
+declare -x SYSTEMD_EXEC_PID="572"
 declare -x USER="runner"
 declare -x VCPKG_INSTALLATION_ROOT="/usr/local/share/vcpkg"
 declare -x XDG_CONFIG_HOME="/home/runner/.config"