ghatm

README

ghatm

ghatm is a command line tool setting timeout-minutes to all GitHub Actions jobs. It finds GitHub Actions workflows and adds timeout-minutes to jobs which don't have the setting. It edits workflow files while keeping YAML comments, indents, empty lines, and so on.

$ ghatm set

diff --git a/.github/workflows/test.yaml b/.github/workflows/test.yaml
index e8c6ae7..aba3b2d 100644
--- a/.github/workflows/test.yaml
+++ b/.github/workflows/test.yaml
@@ -6,6 +6,7 @@ on: pull_request
 jobs:
   path-filter:
     # Get changed files to filter jobs
+    timeout-minutes: 30
     outputs:
       update-aqua-checksums: ${{steps.changes.outputs.update-aqua-checksums}}
       renovate-config-validator: ${{steps.changes.outputs.renovate-config-validator}}
@@ -71,6 +72,7 @@ jobs:
       contents: read
 
   build:
+    timeout-minutes: 30
     runs-on: ubuntu-latest
     permissions: {}
     steps:

Motivation

• https://exercism.org/docs/building/github/gha-best-practices#h-set-timeouts-for-workflows
• job_timeout_minutes_is_required | suzuki-shunsuke/ghalint
• job_timeout_minutes_is_required | lintnet-modules/ghalint

timeout-minutes should be set properly, but it's so bothersome to fix a lot of workflow files by hand. ghatm fixes them automatically.

How to install

ghatm is a single binary written in Go. So you only need to put the executable binary into $PATH.

1. Homebrew

brew install suzuki-shunsuke/ghatm/ghatm

1. Scoop

scoop bucket add suzuki-shunsuke https://github.com/suzuki-shunsuke/scoop-bucket
scoop install ghatm

1. aqua

aqua g -i suzuki-shunsuke/ghatm

1. Download a prebuilt binary from GitHub Releases and install it into $PATH

2. Go

go install github.com/suzuki-shunsuke/ghatm/cmd/ghatm@latest

How to use

Please run ghatm set on the repository root directory.

ghatm set

Then ghatm checks GitHub Actions workflows ^\.github/workflows/.*\.ya?ml$ and sets timeout-minutes: 30 to jobs not having timeout-minutes. Jobs with timeout-minutes aren't changed. You can specify the value of timeout-minutes with -t option.

ghatm set -t 60

You can specify workflow files by positional arguments.

ghatm set .github/workflows/test.yaml

Decide timeout-minutes based on each job's past execution times

ghatm set -auto [-repo <repository>] [-size <the number of sample data>]

ghatm >= v0.3.2 #68 #70

[!warning] The feature doesn't support workflows using workflow_call.

If the -auto option is used, ghatm calls GitHub API to get each job's past execution times and decide appropriate timeout-minutes. This feature requires a GitHub access token with the actions:read permission. You have to set the access token to the environment variable GITHUB_TOKEN or GHATM_GITHUB_TOKEN.

GitHub API:

• List workflow runs for a workflow
• List jobs for a workflow run

ghatm takes 30 jobs by job to decide timeout-minutes. You can change the number of jobs by the -size option.

max(job execution times) + 10

Tips: Fix workflows by CI

Using ghatm in CI, you can fix workflows automatically. When workflow files are added or changed in a pull request, you can run ghatm and commit and push changes to a feature branch.

LICENSE

MIT