Upload a link to the GitHub job

Currently, the observability server UI links to the workflow run attempt
that the upload corresponds to. This is fine in the case where the
workflow only contains a single job, as it did in ably-cocoa. But in the
case where there’s more than one job in a workflow (e.g. in the case of
a matrix build), there’s no way to tell which job an upload corresponds
to. So, include this information in the upload.

Resolves #18.

.github/workflows/check.yml

@@ -5,8 +5,19 @@ on:
       - main
 
 jobs:
+  # An empty job, to allow us to demonstrate how to use job-index inside a
+  # matrix job that has preceding jobs.
+  first-job:
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo "Nothing to see here"
+
   check:
     runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        # Arbitrary; just used so that we can execute inside a matrix job.
+        some-value: [1, 2]
     steps:
       - uses: actions/checkout@v2
 
@@ -31,3 +42,16 @@ jobs:
           server-url: 'https://test-observability.herokuapp.com'
           server-auth: ${{ secrets.TEST_OBSERVABILITY_SERVER_AUTH_KEY }}
           path: 'junit'
+
+      - name: Calculate index of job within workflow
+        # `first-job` + the current job’s index within the matrix
+        run: echo "JOB_INDEX=$((1 + ${{ strategy.job-index }}))" >> $GITHUB_ENV
+
+      - name: Test action with job-index
+        uses: './'
+        with:
+          server-url: 'https://test-observability.herokuapp.com'
+          server-auth: ${{ secrets.TEST_OBSERVABILITY_SERVER_AUTH_KEY }}
+          path: 'junit'
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          job-index: ${{ env.JOB_INDEX }}

README.md

@@ -7,6 +7,8 @@ An action to push JUnit files to Ably's test observability server.
 - `server-url`: the server to publish results to - see [action.yml](./action.yml) for the default value
 - `server-auth`: authentication key for the server. The `ably` GitHub organization has an org-wide `TEST_OBSERVABLILITY_SERVER_AUTH_KEY` secret. It is recommended that you [make this secret available to your repository](https://docs.github.com/en/actions/using-workflows/sharing-workflows-secrets-and-runners-with-your-organization#sharing-secrets-within-an-organization) and then use this secret as the `server-auth` input.
 - `path`: where to look for `*.junit` files
+- `github-token` (optional): A GitHub access token. If provided, the action will perform a GitHub API call in order to discover the web URL for the current job, and will include this URL in the observability server upload. If the repository is private you must use an access token with the `repo` scope.
+- `job-index` (optional): The index to which the current job corresponds in the response from the ["list jobs for a workflow run attempt" GitHub API](https://docs.github.com/en/rest/actions/workflow-jobs?apiVersion=2022-11-28#list-jobs-for-a-workflow-run-attempt). If you specify `github-token` but not `job-index`, and the response from this API contains more than one job, the action will fail.
 
 ## Example
 
@@ -19,4 +21,5 @@ Workflow step:
   with:
     server-auth: ${{ secrets.TEST_OBSERVABLILITY_SERVER_AUTH_KEY }}
     path: '.'
+    github-token: ${{ secrets.GITHUB_TOKEN }}
 ```

action.yml

@@ -13,6 +13,12 @@ inputs:
     description: 'path to .junit report files'
     required: false
     default: 'junit'
+  github-token:
+    description: 'a GitHub access token; if the repository is private then it must have `repo` scope'
+    required: false
+  job-index:
+    description: 'the index to which the current job corresponds in the response from the "list jobs for a workflow run attempt" GitHub API (https://docs.github.com/en/rest/actions/workflow-jobs?apiVersion=2022-11-28#list-jobs-for-a-workflow-run-attempt)'
+    required: false
 runs:
   using: 'node16'
   main: 'dist/index.js'

index.ts

@@ -5,6 +5,56 @@ import fs from 'fs';
 import path from 'path';
 import {got} from 'got';
 
+/**
+ * Fetches the currently-running job from the GitHub API,
+ * so that we can add a link to it in the upload.
+ *
+ * It’s a bit surprising that there’s no built-in functionality
+ * for this (see e.g. https://stackoverflow.com/questions/71240338/obtain-job-id-from-a-workflow-run-using-contexts
+ * or https://github.com/orgs/community/discussions/8945).
+ */
+async function fetchJob() {
+  const githubToken = core.getInput('github-token');
+  if (!githubToken.length) {
+    return null;
+  }
+
+  const octokit = github.getOctokit(githubToken);
+  const response = await octokit.rest.actions.listJobsForWorkflowRunAttempt(
+      {
+        owner: github.context.repo.owner,
+        repo: github.context.repo.repo,
+        run_id: github.context.runId,
+        attempt_number: parseInt(process.env.GITHUB_RUN_ATTEMPT!),
+      },
+  );
+
+  const jobs = response.data.jobs;
+
+  const jobIndexInput = core.getInput('job-index');
+
+  if (jobs.length > 1 && !jobIndexInput.length) {
+    throw new Error(
+        `Got ${jobs.length} jobs from GitHub API \
+         but don’t know which one to pick. You need to \
+         provide a \`job-index\` input.`,
+    );
+  }
+
+  const jobIndex = parseInt(jobIndexInput);
+
+  if (jobIndex >= jobs.length) {
+    throw new Error(
+        `The \`job-index\` input has value ${jobIndex}, \
+        but there are only ${jobs.length} jobs. This \
+        action does not currently handle pagination.`);
+  }
+
+  const job = jobs[jobIndex];
+
+  return job;
+}
+
 // eslint-disable-next-line require-jsdoc
 async function main() {
   const auth = core.getInput('server-auth', {required: true});
@@ -22,6 +72,7 @@ async function main() {
     );
   }
 
+  const job = await fetchJob();
 
   for (const [i, file] of results.entries()) {
     const data = fs.readFileSync(file);
@@ -44,6 +95,8 @@ async function main() {
       iteration: i + 1,
       github_base_ref: process.env.GITHUB_BASE_REF || null,
       github_head_ref: process.env.GITHUB_HEAD_REF || null,
+      github_job_api_url: job?.url ?? null,
+      github_job_html_url: job?.html_url ?? null,
     };