diff-shades comment workflow (psf/black)
The diff-shades comment workflow from psf/black, explained and optimized by Latchkey.
C
CI health: C - fair
Point runs-on at Latchkey and get caching, job timeouts, self-healing for flaky steps, and up to 58% lower cost, applied automatically.
What it does
This is the diff-shades comment workflow from the psf/black repository, a real project running GitHub Actions. It is shown here with attribution under its MIT license.
Below, Latchkey shows a faster, safer version produced by its optimization engine.
The workflow
workflow (.yml)
name: diff-shades comment
on:
workflow_run:
workflows: [diff-shades]
types: [completed]
permissions: {}
jobs:
comment:
runs-on: ubuntu-latest
# We want to comment even if there were failed files or the stable style changed
# That would cause the main workflow to "fail"
if:
github.event.workflow_run.event == 'pull_request' &&
contains(fromJSON('["success", "failure"]'), github.event.workflow_run.conclusion)
permissions:
pull-requests: write # Needed to comment on PR
steps:
- uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
with:
persist-credentials: false
- uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
id: artifacts
with:
merge-multiple: true
pattern: ".*.pr-comment.md"
path: ${{ runner.temp }}/diff-shades-artifacts
github-token: ${{ github.token }}
run-id: ${{ github.event.workflow_run.id }}
- name: Validate downloaded comment artifacts
id: comment-artifacts
shell: bash
run: |
set -euo pipefail
artifact_dir="${RUNNER_TEMP}/diff-shades-artifacts"
preview_artifact="${artifact_dir}/.preview.pr-comment.md"
stable_artifact="${artifact_dir}/.stable.pr-comment.md"
if [ ! -d "$artifact_dir" ]; then
echo "::error::Artifact directory does not exist: ${artifact_dir}"
exit 1
fi
while IFS= read -r -d '' entry; do
if [ "$(dirname "$entry")" != "$artifact_dir" ]; then
echo "::error::Unexpected nested artifact path: ${entry}"
exit 1
fi
case "$(basename "$entry")" in
.preview.pr-comment.md|.stable.pr-comment.md) ;;
*)
echo "::error::Unexpected artifact path: ${entry}"
exit 1
;;
esac
if [ ! -f "$entry" ] || [ -L "$entry" ]; then
echo "::error::Artifact must be a regular file: ${entry}"
exit 1
fi
done < <(find "$artifact_dir" -mindepth 1 -print0)
for artifact in "$preview_artifact" "$stable_artifact"; do
if [ ! -f "$artifact" ] || [ -L "$artifact" ]; then
echo "::error::Missing expected artifact file: ${artifact}"
exit 1
fi
done
{
echo "preview=${preview_artifact}"
echo "stable=${stable_artifact}"
} >> "$GITHUB_OUTPUT"
- name: Set up Python
uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
with:
python-version: "3.14"
pip-version: "25.3"
pip-install: --group diff-shades-comment
- name: Get PR number
id: pr
run:
echo pr=$(gh pr list --search $sha --json number --jq ".[0].number") >>
"$GITHUB_OUTPUT"
env:
GITHUB_TOKEN: ${{ github.token }}
sha: ${{ github.event.workflow_run.head_sha }}
- name: Get details from initial workflow run
id: metadata
run: |
python scripts/diff_shades_gha_helper.py comment-details \
"$pr" "$run_id" "$preview_artifact" "$stable_artifact"
env:
GITHUB_TOKEN: ${{ github.token }}
pr: ${{ steps.pr.outputs.pr }}
run_id: ${{ github.event.workflow_run.id }}
preview_artifact: ${{ steps.comment-artifacts.outputs.preview }}
stable_artifact: ${{ steps.comment-artifacts.outputs.stable }}
- name: Try to find pre-existing PR comment
id: find-comment
uses: peter-evans/find-comment@b30e6a3c0ed37e7c023ccd3f1db5c6c0b0c23aad # v4.0.0
with:
issue-number: ${{ steps.pr.outputs.pr }}
comment-author: "github-actions[bot]"
body-includes: "diff-shades"
- name: Create or update PR comment
uses: peter-evans/create-or-update-comment@e8674b075228eee787fea43ef493e45ece1004c9 # v5.0.0
with:
comment-id: ${{ steps.find-comment.outputs.comment-id }}
issue-number: ${{ steps.pr.outputs.pr }}
body: ${{ steps.metadata.outputs.comment-body }}
edit-mode: replace
The same workflow, on Latchkey
Estimated ~20% faster on cache hits, plus fewer wasted runs and a safer supply chain. Added and changed lines are highlighted.
name: diff-shades comment on: workflow_run: workflows: [diff-shades] types: [completed] permissions: {} jobs: comment: timeout-minutes: 30 runs-on: latchkey-small # We want to comment even if there were failed files or the stable style changed # That would cause the main workflow to "fail" if: github.event.workflow_run.event == 'pull_request' && contains(fromJSON('["success", "failure"]'), github.event.workflow_run.conclusion) permissions: pull-requests: write # Needed to comment on PR steps: - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0 with: persist-credentials: false - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1 id: artifacts with: merge-multiple: true pattern: ".*.pr-comment.md" path: ${{ runner.temp }}/diff-shades-artifacts github-token: ${{ github.token }} run-id: ${{ github.event.workflow_run.id }} - name: Validate downloaded comment artifacts id: comment-artifacts shell: bash run: | set -euo pipefail artifact_dir="${RUNNER_TEMP}/diff-shades-artifacts" preview_artifact="${artifact_dir}/.preview.pr-comment.md" stable_artifact="${artifact_dir}/.stable.pr-comment.md" if [ ! -d "$artifact_dir" ]; then echo "::error::Artifact directory does not exist: ${artifact_dir}" exit 1 fi while IFS= read -r -d '' entry; do if [ "$(dirname "$entry")" != "$artifact_dir" ]; then echo "::error::Unexpected nested artifact path: ${entry}" exit 1 fi case "$(basename "$entry")" in .preview.pr-comment.md|.stable.pr-comment.md) ;; *) echo "::error::Unexpected artifact path: ${entry}" exit 1 ;; esac if [ ! -f "$entry" ] || [ -L "$entry" ]; then echo "::error::Artifact must be a regular file: ${entry}" exit 1 fi done < <(find "$artifact_dir" -mindepth 1 -print0) for artifact in "$preview_artifact" "$stable_artifact"; do if [ ! -f "$artifact" ] || [ -L "$artifact" ]; then echo "::error::Missing expected artifact file: ${artifact}" exit 1 fi done { echo "preview=${preview_artifact}" echo "stable=${stable_artifact}" } >> "$GITHUB_OUTPUT" - name: Set up Python uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0 with: cache: 'pip' python-version: "3.14" pip-version: "25.3" pip-install: --group diff-shades-comment - name: Get PR number id: pr run: echo pr=$(gh pr list --search $sha --json number --jq ".[0].number") >> "$GITHUB_OUTPUT" env: GITHUB_TOKEN: ${{ github.token }} sha: ${{ github.event.workflow_run.head_sha }} - name: Get details from initial workflow run id: metadata run: | python scripts/diff_shades_gha_helper.py comment-details \ "$pr" "$run_id" "$preview_artifact" "$stable_artifact" env: GITHUB_TOKEN: ${{ github.token }} pr: ${{ steps.pr.outputs.pr }} run_id: ${{ github.event.workflow_run.id }} preview_artifact: ${{ steps.comment-artifacts.outputs.preview }} stable_artifact: ${{ steps.comment-artifacts.outputs.stable }} - name: Try to find pre-existing PR comment id: find-comment uses: peter-evans/find-comment@b30e6a3c0ed37e7c023ccd3f1db5c6c0b0c23aad # v4.0.0 with: issue-number: ${{ steps.pr.outputs.pr }} comment-author: "github-actions[bot]" body-includes: "diff-shades" - name: Create or update PR comment uses: peter-evans/create-or-update-comment@e8674b075228eee787fea43ef493e45ece1004c9 # v5.0.0 with: comment-id: ${{ steps.find-comment.outputs.comment-id }} issue-number: ${{ steps.pr.outputs.pr }} body: ${{ steps.metadata.outputs.comment-body }} edit-mode: replace
What changed
- Run on Latchkey managed runners with one line (
runs-on), which apply the fixes below automatically and self-heal transient failures. This example useslatchkey-small; pick the runner size that fits the job. - Cache dependency installs on the setup step so they are served from cache.
- Add a job timeout so a hung step cannot burn hours of runner time.
This workflow runs 1 job per trigger. On Latchkey the same minutes cost up to 58% less than GitHub-hosted, with zero queue time.