Jobs & Steps

## The two shapes of a step A GitHub Actions job carries an ordered `steps:` list. Every entry in that list runs on the same runner, in the same checkout directory, in the order written — and every entry is one of exactly two shapes: - **`uses:`** — invoke somebody's packaged code (an *action*). - **`run:`** — execute shell commands yourself. They are mutually exclusive within a single step. A step with both keys is not "action first, script second" — GitHub rejects the workflow file when it parses it, and the run never starts. If you need both behaviours, write two steps. ## `uses:` — invoking an action `uses:` takes a reference to a unit of packaged, reusable code: - `owner/repo@ref` — the common case, e.g. `actions/checkout@v4`. The `ref` may be a tag, a branch, or a full commit SHA. - `owner/repo/subdirectory@ref` — an action stored in a subfolder of a repository. - `./path/to/action` — an action living in the *same* repository, resolved relative to the workspace, so a checkout must have happened first. - `docker://image:tag` — a container image run directly as the step. Parameters go in `with:`, and their names are not free-form: the action's `action.yml` declares each input, whether it is required, and its default. Passing a name the action does not declare is silently ignored rather than helpful, which is why a typo in `with:` usually shows up as "the action did nothing". What the action *does* — checkout, cache restore, cloud login — is opaque to your workflow; it just runs and may expose step outputs. ## `run:` — executing commands `run:` takes a command string, or a multi-line block via YAML's `|`: ``` - run: | ./gradlew build ls build/libs ``` Things worth internalising about `run:`: - **One shell process per step.** State that lives only in the shell — the current directory, an exported variable, a shell function — is gone when the step ends. To carry a variable forward, append `NAME=value` to the file named by `$GITHUB_ENV`; to add a directory to `PATH` for later steps, append it to `$GITHUB_PATH`. - **Working directory** defaults to the workspace (`github.workspace`). Override per step with `working-directory:`. - **Shell** defaults to `bash` on Linux and macOS runners and `pwsh` on Windows runners; set it explicitly with `shell:`. Setting `shell: bash` explicitly is not identical to the default — the explicit form runs with `-o pipefail`, so a failing command in the middle of a pipe fails the step. - **Exit code is the verdict.** Non-zero fails the step, and by default every later step in the job is skipped. ## Keys that apply to both `name`, `id`, `if`, `env`, `continue-on-error` and `timeout-minutes` are valid on either shape. `id` matters most: it is how later steps reference this step's outputs through the `steps` context. ## Cutting repetition with defaults and env Rather than repeating `shell:` and `working-directory:` on every command step, set them once: ``` defaults: run: shell: bash working-directory: backend ``` This block is legal at workflow level and at job level, and it affects `run:` steps only — an action invoked with `uses:` decides its own working directory. Similarly, an `env:` map may sit at workflow, job, or step level, with the innermost definition winning. ## Choosing between them Reach for `run:` when the logic is specific to this repository and short: invoking your build tool, moving a file, printing a diagnostic. Reach for `uses:` when the work is generic and someone has already solved the cross-platform and caching details — checking out the repository, setting up a language toolchain, restoring a cache, uploading an artifact. The cost of `uses:` is trust: a third-party action executes with access to the job's workspace and whatever secrets you hand it, which is why teams pin such references to a full commit SHA rather than a moving tag. The cost of `run:` is that you own the portability and the error handling yourself.