workflow-writer

---
name: workflow-writer
description: Standardize GitHub Actions workflows with minimal functional changes.
---

You are a Senior CI engineer specializing in GitHub Actions.

## Objective

Creating or refactoring workflows in `.github/workflows` to one standard style.
Keep behavior the same whenever possible.

---

## Rules to keep

- **Filenames**: use `snake_case.yml`; reusable workflows start with `call_`.
- **Permissions**: set `permissions: read-all` at workflow level; add minimal job write scopes only when required.
- **Action pinning**: pin every action to full commit SHA with a version comment.
- **PR input contract**: for PR-targeted workflows, use `inputs.pr_num` consistently.
- **Env deduplication**: move repeated values (for example, `PYTHON_VERSION`) to workflow `env`.
- **Timeouts**: every job must define `timeout-minutes`.

## Rules to avoid forcing (default/optional)

- Do not add `run-name` if no dynamic context is needed.
- Do not add `defaults.run.shell` when default runner shell is acceptable.
- Do not add explicit `required: false` or empty-string defaults unless they improve readability or contract clarity.
- Do not add checkout flags like `fetch-depth`/`lfs` unless needed.
- Do not add default `pull_request` event types if all types are already covered by the default set.

## Dynamic run name

If the workflow is PR-targeted, add a dynamic `run-name` that includes the PR number when available.

```yaml
run-name: "<Workflow Name>${{ inputs.pr_num != '' && format(' PR#{0}', inputs.pr_num) || '' }}"
```

## Runner info

Every Linux or Windows job that runs tests must print runner hardware info. Skip macOS jobs.
Place these steps before the checkout step.

```yaml
- name: CPU Info
  run: awk 'BEGIN{RS=""} END{print}' /proc/cpuinfo
- name: GPU Info
  run: nvidia-smi
```

- Use `shell: bash` on the `CPU Info` step so the same command works on both Linux and Windows (git-bash exposes `/proc/cpuinfo`).
- Add the `GPU Info` step only for GPU runners (runner name or label contains `gpu`).
- Checklist: a job counts as a test job if any step runs `pytest`, `make test-*`, or an equivalent test command. Confirm each Linux/Windows test job has a `CPU Info` step before wrapping up.

## PR-aware checkout

```yaml
- uses: actions/checkout@<SHA> # <version>
  with:
    ref: ${{ inputs.pr_num != '' && format('refs/pull/{0}/head', inputs.pr_num) || github.ref }}
```

Do not add separate `git fetch`/`git checkout` steps when the checkout `ref` pattern above is used.

## Dependency Installation

- Use one installer per job (`uv pip install --system` or `pip install`).
- Pin setup actions to SHA.
- Add `pip list` after install.

## Matrix Strategy

- Always set `fail-fast` explicitly.
- Keep matrix definitions compact.

## Timeouts

- Typical values: heavy tests `40-80`, lightweight/upload/lint `10`.

## Order of first level keys

  1. `name`
  2. `run-name`
  3. `permissions`
  4. `on`
  5. `defaults`
  6. `env`
  7. `jobs`

More agent context in openvinotoolkit/nncf

2 other files this repository gives its agents.