jobs.<job_id>.timeout-minutes description is misleading

[jsoref]

What article on docs.github.com is affected?

https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions#jobsjob_idtimeout-minutes

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

jobs.<job_id>.timeout-minutes
The maximum number of minutes to let a job run before GitHub automatically cancels it. Default: 360

Additional information

The text isn't technically wrong, but it's misleading.

Yes, if you use a self-hosted runner, you can set a value that's larger than 360, but if you are using GitHub hosted runners, then this limit is actually a hard limit:

https://docs.github.com/en/actions/reference/usage-limits-billing-and-administration#usage-limits

Job execution time - Each job in a workflow can run for up to 6 hours of execution time. If a job reaches this limit, the job is terminated and fails to complete.

6*60 = 360

Problems:

1. The text really should explain that 360 is a hard max for GitHub runners explaining that people using GitHub runners can only reduce the limit (to prevent throwing away GitHub minutes, or GitHub billable minutes).
2. Why does one page use 360 minutes while the other list 6 hours? Sure, they're technically equivalent, but by using different units, it makes searching for a value in the other document hard.

[jsoref]

Confused user: https://github.heygears.community/t/workflow-was-terminated-after-360-minutes-but-config-have-set-timeout-minutes-to-600/188631

[ramyaparimi]

@jsoref Thank you for opening this issue 👍 I will triage it for review ⚡

[skedwards88]

Thanks for opening this issue! I agree that we should mention time limits here. The text in Workflow syntax for GitHub Actions - GitHub Docs could be changed to something like:

The maximum number of minutes to let a job run before GitHub automatically cancels it. Default: 360

If the timeout exceeds the job execution time limit for the runner, the job will be canceled when the execution time limit is met instead. For more information about job execution time limits, see "[Usage limits, billing, and administration](/actions/reference/usage-limits-billing-and-administration#usage-limits)."

You or anyone else is welcome to open a PR with this addition.

Although you are correct that changing 6 hours to 360 minutes in Usage limits, billing, and administration would be more consistent across articles, I recommend keeping it as 6 hours so that unit comparison within the article is easier (e.g. job limit is 6 hours, and workflow limit is 72 hours).

[lucalves]

Hello, I opened #8362 to solve this.

[jsoref]

@skedwards88, @lucalves: I wouldn't write it that way.

It isn't technically wrong, but it's too easy for someone to misparse.

(I'm currently dealing with another project which is failing to properly parse an RFC.)

You need to include text that hints that the jobs value is clamped by a second value. Or similarly that if the value exceeds the second value, it is ignored and that second value is honored instead.

[skedwards88]

@skedwards88, @lucalves: I wouldn't write it that way.

It isn't technically wrong, but it's too easy for someone to misparse.

(I'm currently dealing with another project which is failing to properly parse an RFC.)

You need to include text that hints that the jobs value is clamped by a second value. Or similarly that if the value exceeds the second value, it is ignored and that second value is honored instead.

Thanks for this input, @jsoref. Could you open a PR or comment with specific text that you think would be clearer? In the interest of moving this forward, I will merge @lucalves 's PR, but we are open to additional improvements.