docs: Update job_name description (#23)

Tiryoh · Feb 20, 2023 · 9f171e6 · 9f171e6
1 parent 0fadc5f
commit 9f171e6
Showing 1 changed file with 101 additions and 15 deletions.
diff --git a/README.md b/README.md
@@ -12,9 +12,26 @@ https://developer.github.com/v3/actions/workflow_jobs/
 
 **Required** GITHUB_TOKEN to use GitHub API v3
 
+Simply, just specify `${{ secrets.GITHUB_TOKEN }}`.
+
 ### `job_name`
 
-**Required** job_name of tartget workflow jobs
+**Required** `jobs.<job-id>.name` of tartget workflow jobs
+
+If no name specified, use `jobs.<job-id>` instead. Note that `<job-id>` != job_id.  
+If you are using this actions with matrix workflow, check the example section.
+
+
+```yaml
+jobs:
+  my_first_job:         # this is jobs.<job-id>
+    name: My first job  # this is jobs.<job-id>.name
+  my_second_job:        # this is jobs.<job-id>
+    name: My second job # this is jobs.<job-id>.name
+```
+
+* `jobs.<job-id>`: https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_id
+* `jobs.<job-id>.name`: https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idname
 
 ### `repository`
 
@@ -54,28 +71,97 @@ The job using this GitHub Actions must have the `actions:read` permission.
 
 ## Example usage
 
-### Get current `job_id` URL
+### Simple example 1
 
 ```yaml
-- name: Get Current Job Log URL
-  uses: Tiryoh/gha-jobid-action@v0
-  id: jobs
-  with:
-    github_token: ${{ secrets.GITHUB_TOKEN }}
-    job_name: @@JOB_NAME@@
-    per_page: 30
+name: CI
+on:
+  push:
+permissions:
+  actions: read
+  contents: read # required by actions/checkout
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout action
+        uses: actions/checkout@v3
+      - name: Some Scripts
+        run: echo "do something here"
+      - name: Get Current Job Log URL
+        uses: Tiryoh/gha-jobid-action@v0
+        id: jobs
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          job_name: "build" # input job.<job-id>
+          #job_name: "${{ github.job }}"  # if job.<job-id>.name is not specified, this works too
+      - name: Output Current Job Log URL
+        run: echo ${{ steps.jobs.outputs.html_url }}
 ```
 
-https://github.com/Tiryoh/docker-ros2-desktop-vnc/blob/ad3b893722b3f56c3e772e5f43efb2eb1bf682fb/.github/workflows/deploy.yml#L64-L69
+### Simple example 2
+
+```yaml
+name: CI
+on:
+  push:
+permissions:
+  actions: read
+  contents: read # required by actions/checkout
+jobs:
+  build:
+    name: Build and Test
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout action
+        uses: actions/checkout@v3
+      - name: Some Scripts
+        run: echo "do something here"
+      - name: Get Current Job Log URL
+        uses: Tiryoh/gha-jobid-action@v0
+        id: jobs
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          job_name: "Build and Test" # input job.<job-id>.name here. job.<job-id> won't works.
+      - name: Output Current Job Log URL
+        run: echo ${{ steps.jobs.outputs.html_url }}
+```
 
-### Output `job_id` URL
+### Matrix example
 
 ```yaml
-- name: Output Current Job Log URL
-  run: echo ${{ steps.jobs.outputs.html_url }}
+name: CI
+on:
+  push:
+permissions:
+  actions: read
+  contents: read # required by actions/checkout
+jobs:
+  build:
+    strategy:
+      matrix:
+        distro: [alpha, beta, gamma]
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout action
+        uses: actions/checkout@v3
+      - name: Some Scripts
+        run: echo "do something here ${{ matrix.distro }}"
+      - name: Get Current Job Log URL
+        uses: Tiryoh/gha-jobid-action@v0
+        id: jobs
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          job_name: "build (${{ matrix.distro }})" # input job.<job-id>.name and matrix here.
+          per_page: 50 # input matrix size here if it is larger than 30
+      - name: Output Current Job Log URL
+        run: echo ${{ steps.jobs.outputs.html_url }}
 ```
 
-https://github.com/Tiryoh/docker-ros2-desktop-vnc/blob/ad3b893722b3f56c3e772e5f43efb2eb1bf682fb/.github/workflows/deploy.yml#L88
+* Get current `job_id` URL
+  * https://github.com/Tiryoh/docker-ros2-desktop-vnc/blob/ad3b893722b3f56c3e772e5f43efb2eb1bf682fb/.github/workflows/deploy.yml#L64-L69
+* Output `job_id` URL
+  * https://github.com/Tiryoh/docker-ros2-desktop-vnc/blob/ad3b893722b3f56c3e772e5f43efb2eb1bf682fb/.github/workflows/deploy.yml#L88
 
 ## Contributors
 
@@ -94,7 +180,7 @@ Contributions are always welcome!
 
 ## License
 
-Copyright (c) 2020-2022 Daisuke Sato
+Copyright (c) 2020-2023 Daisuke Sato
 
 This repository is licensed under the MIT License, see [LICENSE](./LICENSE).  
 Unless attributed otherwise, everything in this repository is licensed under the MIT license.