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

2. Scoop

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

3. aqua

aqua g -i suzuki-shunsuke/ghatm

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

Verify downloaded assets from GitHub Releases

You can verify downloaded assets using some tools.

1. GitHub CLI
2. slsa-verifier
3. Cosign

--

1. GitHub CLI

ghatm >= v0.3.3

You can install GitHub CLI by aqua.

aqua g -i cli/cli

gh release download -R suzuki-shunsuke/ghatm v0.3.3 -p ghatm_darwin_arm64.tar.gz
gh attestation verify ghatm_darwin_arm64.tar.gz \
  -R suzuki-shunsuke/ghatm \
  --signer-workflow suzuki-shunsuke/go-release-workflow/.github/workflows/release.yaml

Output:

Loaded digest sha256:84298e8436f0b2c7f51cd4606848635471a11aaa03d7d0c410727630defe6b7e for file://ghatm_darwin_arm64.tar.gz
Loaded 1 attestation from GitHub API
✓ Verification succeeded!

sha256:84298e8436f0b2c7f51cd4606848635471a11aaa03d7d0c410727630defe6b7e was attested by:
REPO                                 PREDICATE_TYPE                  WORKFLOW
suzuki-shunsuke/go-release-workflow  https://slsa.dev/provenance/v1  .github/workflows/release.yaml@7f97a226912ee2978126019b1e95311d7d15c97a

2. slsa-verifier

You can install slsa-verifier by aqua.

aqua g -i slsa-framework/slsa-verifier

gh release download -R suzuki-shunsuke/ghatm v0.3.3 -p ghatm_darwin_arm64.tar.gz  -p multiple.intoto.jsonl
slsa-verifier verify-artifact ghatm_darwin_arm64.tar.gz \
  --provenance-path multiple.intoto.jsonl \
  --source-uri github.com/suzuki-shunsuke/ghatm \
  --source-tag v0.3.3

Output:

Verified signature against tlog entry index 137035428 at URL: https://rekor.sigstore.dev/api/v1/log/entries/108e9186e8c5677a421587935f03afc5f73475e880b6f05962c5be8726ccb5011b7bf62a5d2a58bb
Verified build using builder "https://github.com/slsa-framework/slsa-github-generator/.github/workflows/generator_generic_slsa3.yml@refs/tags/v2.0.0" at commit 1af80d4aa0b6cc45bda5677fd45202ee2b90e1fc
Verifying artifact ghatm_darwin_arm64.tar.gz: PASSED

3. Cosign

You can install Cosign by aqua.

aqua g -i sigstore/cosign

gh release download -R suzuki-shunsuke/ghatm v0.3.3
cosign verify-blob \
  --signature ghatm_0.3.3_checksums.txt.sig \
  --certificate ghatm_0.3.3_checksums.txt.pem \
  --certificate-identity-regexp 'https://github\.com/suzuki-shunsuke/go-release-workflow/\.github/workflows/release\.yaml@.*' \
  --certificate-oidc-issuer "https://token.actions.githubusercontent.com" \
  ghatm_0.3.3_checksums.txt

Output:

Verified OK

After verifying the checksum, verify the artifact.

cat ghatm_0.3.3_checksums.txt | sha256sum -c --ignore-missing

5. 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