/github-actions-style

name: github-actions-style
description: GitHub Actions workflow and composite action conventions for MLflow. Use when writing, modifying, or reviewing workflows in .github/workflows/ or actions in .github/actions/ in this repository.

GitHub Actions Workflow Guidelines

Reinvent the Wheel When It's Cheap

Prefer a small `run:` step or repository script over a third-party action when the behavior is straightforward and cheap to implement and maintain. Use tools already available in the job, such as `gh`, `curl`, or Python. A few lines of code can avoid another dependency to audit, pin, and update, reduce exposure to supply chain attacks, and skip the action's download overhead.

# Bad: adds a dependency just to label a PR
- uses: example/label-pr@...
  with:
    label: needs-review

# Good
- env:
    GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    PR_NUMBER: ${{ github.event.pull_request.number }}
    REPO: ${{ github.repository }}
  run: gh pr edit "$PR_NUMBER" --repo "$REPO" --add-label needs-review

Use a third-party action when it provides substantial functionality that would be costly or error-prone to reproduce.

Use `ubuntu-slim` for Lightweight Tasks

Prefer `ubuntu-slim` over `ubuntu-24.04` for simple jobs (e.g., labeling, commenting, notifications).

Note: `ubuntu-slim` has a 15-minute timeout limit. Use `ubuntu-24.04` for long-running jobs (e.g., polling).

# Bad
runs-on: ubuntu-24.04

# Good
runs-on: ubuntu-slim

Use Workflow Context Instead of Fetching

If the trigger event already carries the data, read it from the `github` context instead of calling `gh` or `actions/github-script`. Extra API calls burn rate-limit budget and add a flaky network hop for nothing.

# Bad
- env:
    GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    PR_NUMBER: ${{ github.event.pull_request.number }}
  run: |
    HEAD_SHA=$(gh pr view "$PR_NUMBER" --json headRefOid -q .headRefOid)

# Good
- env:
    HEAD_SHA: ${{ github.event.pull_request.head.sha }}
  run: echo "$HEAD_SHA"

Only fetch when the data isn't in the payload (e.g., check runs, review threads, changed files on `issue_comment`).

Prefer Job Conditions Over Shell Guards

When a condition determines whether a job has any work and can be evaluated from workflow contexts, use a job-level `if` instead of starting a `run` script and checking the condition in the shell. GitHub can then skip the job without provisioning a runner.

# Bad: every opened issue provisions a runner before checking its title
jobs:
  label:
    runs-on: ubuntu-slim
    steps:
      - env:
          ISSUE_TITLE: ${{ github.event.issue.title }}
        run: |
          if echo "$ISSUE_TITLE" | grep -qi "bug report"; then
            gh issue edit ... --add-label bug
          fi

# Good: unrelated issues skip the job before a runner is provisioned
jobs:
  label:
    if: contains(github.event.issue.title, 'bug report')
    runs-on: ubuntu-slim
    steps:
      - run: gh issue edit ... --add-label bug

Keep the condition inside `run` when it depends on information produced on the runner or a command's result and cannot be evaluated as a workflow expression.

Prefer `gh` CLI over `actions/github-script`

For simple GitHub API operations (commenting, labeling, cancelling runs, etc.), use `gh` CLI instead of `actions/github-script`. It avoids the need for `actions/checkout` and JavaScript boilerplate.

# Bad
- uses: actions/checkout@...
- uses: actions/github-script@...
  with:
    script: |
      const script = require(".github/workflows/my-script.js");
      await script({ context, github });

# Good
- env:
    GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
  run: |
    gh pr comment ...

Prefer `GITHUB_TOKEN` When Its Scope and Trigger Behavior Are Sufficient

Use `${{ secrets.GITHUB_TOKEN }}` by default for operations in the current repository when its job-level permissions are sufficient. Use `actions/create-github-app-token` when access to other repositories or separately scoped credentials is required, or when the resulting GitHub event must trigger another workflow. Events created with `GITHUB_TOKEN` [generally do not trigger workflow runs](https://docs.github.com/en/actions/how-tos/write-workflows/choose-when-workflows-run/trigger-a-workflow).

# Bad: this comment does not need to trigger another workflow
- uses: actions/create-github-app-token@...
  id: app-token
  with:
    # ...
- env:
    GH_TOKEN: ${{ steps.app-token.outputs.token }}
  run: gh issue comment ...

# Good
- env:
    GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
  run: gh issue comment ...

Prefer the Shared Setup Actions

Set up toolchains through the composite actions in `.github/actions/` rather than calling the upstream actions directly. Each one centralizes the pinned version and the env defaults every job expects, so an upstream bump stays a one-line change instead of a repo-wide sweep.

| Toolchain | Action | | --------------- | -------------------------------- | | Python and `uv` | `./.github/actions/setup-python` | | Node | `./.github/actions/setup-node` | | Java | `./.github/actions/setup-java` |

# Bad: a second copy of the pin to keep in sync, and no uv or env defaults
- uses: actions/setup-python@...

# Good
- uses: ./.github/actions/setup-python

Local action paths resolve relative to `$GITHUB_WORKSPACE`, so a workflow that checks the repo out into a subdirectory needs that prefix (`./mlflow/.github/actions/setup-python`). Never point it at a PR head checkout: that runs author-controlled code with whatever secrets the workflow holds.

Use `sparse-checkout` When Only a Subset of Files Is Needed

When a workflow only needs a small subset of the repo (e.g., a single script under `.github/`), pass `sparse-checkout` to `actions/checkout` instead of cloning the whole tree. A full checkout of this repo takes around 10 seconds on average; a sparse chec