RUNNER_NAME and /repos/{owner}/{repo}/actions/runs/{run_id}/jobs are incorrectly documented

[jsoref]

Code of Conduct

• I have read and agree to the GitHub Docs project's Code of Conduct

What article on docs.github.com is affected?

https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/store-information-in-variables#default-environment-variables

What part(s) of the article would you like to see updated?

https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/store-information-in-variables#default-environment-variables

Variable	Description
RUNNER_NAME	The name of the runner executing the job. This name may not be unique in a workflow run as runners at the repository and organization levels could use the same name. For example, Hosted Agent

https://docs.github.com/en/rest/actions/workflow-jobs?apiVersion=2022-11-28#list-jobs-for-a-workflow-run

example response

{
  "total_count": 1,
  "jobs": [
    {
      "id": 399444496,
      "run_id": 29679449,
      "run_url": "https://api.github.com/repos/octo-org/octo-repo/actions/runs/29679449",
      "node_id": "MDEyOldvcmtmbG93IEpvYjM5OTQ0NDQ5Ng==",
      "head_sha": "f83a356604ae3c5d03e1b46ef4d1ca77d64a90b0",
      "url": "https://api.github.com/repos/octo-org/octo-repo/actions/jobs/399444496",
      "html_url": "https://github.com/octo-org/octo-repo/runs/29679449/jobs/399444496",
      "status": "completed",
      "conclusion": "success",
      "started_at": "2020-01-20T17:42:40Z",
      "completed_at": "2020-01-20T17:44:39Z",
      "name": "build",
      "steps": [
        {
          "name": "Set up job",
          "status": "completed",
          "conclusion": "success",
          "number": 1,
          "started_at": "2020-01-20T09:42:40.000-08:00",
          "completed_at": "2020-01-20T09:42:41.000-08:00"
        },
        {
          "name": "Run actions/checkout@v2",
          "status": "completed",
          "conclusion": "success",
          "number": 2,
          "started_at": "2020-01-20T09:42:41.000-08:00",
          "completed_at": "2020-01-20T09:42:45.000-08:00"
        },
        {
          "name": "Set up Ruby",
          "status": "completed",
          "conclusion": "success",
          "number": 3,
          "started_at": "2020-01-20T09:42:45.000-08:00",
          "completed_at": "2020-01-20T09:42:45.000-08:00"
        },
        {
          "name": "Run actions/cache@v3",
          "status": "completed",
          "conclusion": "success",
          "number": 4,
          "started_at": "2020-01-20T09:42:45.000-08:00",
          "completed_at": "2020-01-20T09:42:48.000-08:00"
        },
        {
          "name": "Install Bundler",
          "status": "completed",
          "conclusion": "success",
          "number": 5,
          "started_at": "2020-01-20T09:42:48.000-08:00",
          "completed_at": "2020-01-20T09:42:52.000-08:00"
        },
        {
          "name": "Install Gems",
          "status": "completed",
          "conclusion": "success",
          "number": 6,
          "started_at": "2020-01-20T09:42:52.000-08:00",
          "completed_at": "2020-01-20T09:42:53.000-08:00"
        },
        {
          "name": "Run Tests",
          "status": "completed",
          "conclusion": "success",
          "number": 7,
          "started_at": "2020-01-20T09:42:53.000-08:00",
          "completed_at": "2020-01-20T09:42:59.000-08:00"
        },
        {
          "name": "Deploy to Heroku",
          "status": "completed",
          "conclusion": "success",
          "number": 8,
          "started_at": "2020-01-20T09:42:59.000-08:00",
          "completed_at": "2020-01-20T09:44:39.000-08:00"
        },
        {
          "name": "Post actions/cache@v3",
          "status": "completed",
          "conclusion": "success",
          "number": 16,
          "started_at": "2020-01-20T09:44:39.000-08:00",
          "completed_at": "2020-01-20T09:44:39.000-08:00"
        },
        {
          "name": "Complete job",
          "status": "completed",
          "conclusion": "success",
          "number": 17,
          "started_at": "2020-01-20T09:44:39.000-08:00",
          "completed_at": "2020-01-20T09:44:39.000-08:00"
        }
      ],
      "check_run_url": "https://api.github.com/repos/octo-org/octo-repo/check-runs/399444496",
      "labels": [
        "self-hosted",
        "foo",
        "bar"
      ],
      "runner_id": 1,
      "runner_name": "my runner",
      "runner_group_id": 2,
      "runner_group_name": "my runner group",
      "workflow_name": "CI",
      "head_branch": "main"
    }
  ]
}

      "runner_name": "my runner",

https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/accessing-contextual-information-about-workflow-runs#runner-context

Property name	Type	Description
runner.name	string	The name of the runner executing the job. This name may not be unique in a workflow run as runners at the repository and organization levels could use the same name.

Additional information

Between https://github.com/check-spelling-sandbox/check-spelling/actions/runs/13813316120 and https://github.com/check-spelling-sandbox/check-spelling/actions/runs/13835035831 the behavior of RUNNER_NAME and the github runner api changed.

In the first run, RUNNER_NAME and runner_name had matching behavior. In the second run, RUNNER_NAME is equivalent to runner_name (with spaces changed to _...) + "_" + runner_id.

Note that there is no id property in the runner context and that the runner context name now appears to include a runner id (at least for github hosted runners).

[jsoref]

For my reference, I added code to handle this change:
check-spelling/check-spelling@75e8f6b

which results in things working again:
https://github.com/check-spelling/check-spelling/actions/runs/14014671669/attempts/1#summary-39238824999

Note that nothing mentions that some of these things mangle spaces into -s either...

[github-actions]

Thanks for opening an issue! We've triaged this issue for technical review by a subject matter expert 👀

[Sharra-writes]

@jsoref Thanks so much for opening a PR! I'll see if one of our SMEs can take a look.

[ericsciple]

@jsoref apologies for the disruption. We have rolled out a fix now for the issue.

[ericsciple]

@jsoref also, thank you for reporting this issue.

[jsoref]

@ericsciple: I don't suppose you can point to what the change looks like?

My current items aren't working:
https://github.com/check-spelling-sandbox/autotest-check-spelling/actions/runs/14661955026#summary-41148183293

Whereas they worked ~3 days ago:
https://github.com/check-spelling-sandbox/autotest-check-spelling/actions/runs/14591993355#summary-40929159295

[ericsciple]

@jsoref, $RUNNER_NAME is now fixed to match the response from list-jobs-for-a-workflow-run

Here is a sample from my personal repo:

$RUNNER_NAME is GitHub Actions 1000000114

Excerpt from list-jobs-for-a-workflow-run response:

      "runner_id": 1000000114,
      "runner_name": "GitHub Actions 1000000114",

[jsoref]

Thanks, a slight change from check-spelling/check-spelling@75e8f6b to check-spelling/check-spelling@8360222 seems to have resulted in things working again.

[ericsciple]

@jsoref, out of curiosity, now that the fix has rolled out and $RUNNER_NAME matches the payload from lists-jobs-for-a-workflow-run, I'm wondering whether the original command would work again:

jq -r '.jobs[] | select(.status=="in_progress" and .runner_name=="'"$RUNNER_NAME"'" and .run_attempt=='"${GITHUB_RUN_ATTEMPT:-1}"')' "$jobs_info" > "$job" 2>/dev/null

I am about to step away but I can test this later as well.

[jsoref]

@ericsciple yes, it works: https://github.com/check-spelling-sandbox/check-spelling/actions/runs/14673909814/attempts/1#summary-41186421291.

Is this a promise not to make this breaking change again? Most people won't be running prerelease which means that I need to eventually make a release and have some faith that it'll work for a while (6-12 months)
If it's likely that you're going to make this change in the future, I'd rather leave a forwards-compatible shim in place...

[ericsciple]

@jsoref, awesome! Thanks for confirming.

Yes, this breaking change was unintentional. I will add an end-to-end test, so we don't accidentally regress this behavior again in the future. Again, apologies for the disruption and thank you for helping us identify this unintentional breaking change.

[ericsciple]

I will let you know you shortly after the end-to-end test is in place (probably today or tomorrow).

[ericsciple]

@jsoref an end-to-end test has been added now

[jsoref]

Thanks @ericsciple. I guess we can close this as resolved completed as the documentation now matches the implementation and there's an end-to-end test to enforce that.

[Sharra-writes]

Thanks, @jsoref! I'm glad the issue got resolved. 👍