A CI job runs in an environment you must describe
Make a CI job’s runtime, permissions and working directory explicit, and understand which state survives between steps.

A CI job runs in an environment chosen by its workflow and runner configuration. Describe that environment before treating a local success as evidence that CI should succeed. The working directory, available runtime, permissions and process boundaries can all differ from a developer’s terminal.
If you are adding your first GitHub Actions check, begin with a small job whose output is easy to inspect. It can establish the execution contract without downloading dependencies or accessing a production account.
Start with a job that needs no repository token
This complete teaching workflow creates a harmless file in one step and reads it in another. Save it under .github/workflows/ in a practice repository if you want to dispatch it there. The manual-event reference requires the workflow file to exist on the default branch. The examples here are checked locally; no hosted workflow run is claimed:
name: Inspect the job environment
on: [workflow_dispatch]
permissions: {}
jobs:
inspect:
runs-on: ubuntu-24.04
defaults:
run:
shell: bash
env:
LAB_MODE: verify
steps:
- name: Create the fixture
run: |
printf 'mode=%s\n' "$LAB_MODE"
printf 'directory=%s\n' "$PWD"
mkdir -p fixture
printf '%s\n' 'expected marker' > fixture/result.txt
- name: Read the earlier file
working-directory: fixture
run: |
test "$(cat result.txt)" = 'expected marker'
The workflow requests no repository-token permissions because it does not need to read the repository through an action or call an API. It runs only when manually dispatched. This permission setting governs the repository token; it is not an operating-system sandbox or a prohibition on network access. The runner label selects an operating-system image family; it does not freeze every package revision on that image.
The second step can read the file because steps in this job share the runner’s workspace. They do not share one continuously running shell. An ordinary shell variable assigned inside the first step would not automatically become a variable in the second step.
The filesystem persists between these steps on the job’s runner. Shell-local state belongs to each step’s process, while declared job environment variables are supplied to the step processes.
Make the shell and directory intentional
A command interpreted by Bash can behave differently under another shell. Quoting, pipelines and error handling are part of that interpreter’s contract. Specify the shell when the script relies on its features, and test a repository script directly rather than maintaining a second slightly different implementation in YAML.
The working directory determines where relative paths point. A command such as npm ci may fail because it cannot find the expected lockfile, even when the runtime and network are fine. Inspect the intended directory and the files the step needs before changing package-manager settings.
For a repository-based check, checkout is another explicit step. A runner does not necessarily contain the repository simply because the workflow belongs to it. The chosen checkout reference also matters for pull requests, where testing a merge result and testing a branch head are different procedures.
The workflow-syntax reference defines jobs, steps, defaults, permissions and environment fields. Keep those definitions near the workflow design rather than inferring behavior from what happened to work on one runner.
Pin the runtime at the level the project supports
A hosted runner includes many tools, but their preinstalled versions can change. A project should select its supported language runtime through an appropriate setup step or controlled container image and report the version used during a failure.
A major-version selection is useful for compatibility testing. An exact version or digest provides a narrower reproducibility boundary. Neither choice is universally correct: a compatibility job may intentionally track updates, while a release build may need an explicitly reviewed toolchain identity.
Record package-manager versions when lockfile or installation behavior depends on them. A runtime version alone may not describe the complete toolchain. Also distinguish the runner operating system from a container used by a particular job or action; commands can execute inside a different filesystem and userspace from the runner host.
Pass state through declared channels
Use files or documented workflow outputs when a later step needs a computed result. GitHub’s environment-file mechanism can supply values to subsequent steps, but writing to that file does not retroactively change the current shell’s variables. The format also needs care for multiline or untrusted values.
Do not print the entire environment to diagnose one missing setting. A precise check can report whether a required variable is present without displaying its contents. The teaching workflow prints only its harmless declared mode and working directory.
Different jobs may run on different machines. A file left in one job’s workspace is not an implicit input to another job. Use an artifact, a defined external store or another supported transfer mechanism, and identify the result being passed. The same workflow file does not imply shared local storage across jobs.
Match failures to the boundary that changed
If a step cannot find a file, inspect checkout and directory selection. If an API rejects a request, inspect the effective permission and identity. If a command behaves differently, inspect the shell, runtime and input versions. These checks are more specific than rerunning the whole workflow until it turns green.
A useful failure record contains the workflow revision, runner environment, tool versions and exact step that failed, with secrets excluded. For the fixture, success is simply the second step reading the expected bytes. Once that basic contract is visible, add the application’s actual checks one at a time so each new dependency has an owner and an observable failure.
Observe the handoff between two fresh shells
Append these two step entries to the same job’s steps list. They use only the declared harmless values. The first exports a shell variable and writes a different value to the runner’s environment file. The second checks which state reached its new process and overrides the job’s mode for that step alone.
- name: Publish a later-step value
run: |
export CI_LAB_LOCAL='this shell'
printf 'CI_LAB_RESULT=%s\n' 'published' >> "$GITHUB_ENV"
printf 'current result=%s\n' "${CI_LAB_RESULT-unset}"
- name: Read the runner-supplied value
env:
LAB_MODE: step-specific
run: |
test "${CI_LAB_LOCAL-unset}" = unset
test "$CI_LAB_RESULT" = published
test "$LAB_MODE" = step-specific
test "$(cat fixture/result.txt)" = 'expected marker'
printf 'later result=%s; mode=%s\n' "$CI_LAB_RESULT" "$LAB_MODE"
Under the teaching workflow’s initial environment, the first new step prints current result=unset. Writing text into a file does not assign a shell variable. After that step finishes, the runner processes the file and supplies the value to subsequent steps. The next step prints later result=published; mode=step-specific. Meanwhile, the exported local variable is absent: it would be inherited by children launched from its shell, not by a new sibling step process launched by the runner.
GitHub’s environment-file reference specifies this later-step availability. It also requires suitable encoding and documents multiline delimiters and restricted variable names. This example writes a fixed single-line value. Do not turn arbitrary multiline input into this format by string concatenation, and do not source an untrusted environment file as shell code to imitate the runner. Parsing data and executing shell syntax are different operations.
The table separates three mechanisms: a process export, runner-managed state transfer and a step-specific environment setting. The mode override applies while that step executes. A later step without that override returns to the declared job mode, assuming no other deliberate update of that variable. This is why checking a variable’s name is insufficient; locate the scope that supplies its current value.
Notice the relative file path in the last step. The earlier reader used working-directory: fixture, but that per-step setting does not make every later shell start there. The new step again starts in the job’s default working directory and reads fixture/result.txt. Similarly, a cd command changes its current shell’s directory; it does not rewrite the next step’s working-directory setting.
Reproduce the shell boundary without pretending to run GitHub
A local check can start a new Bash process for every run block, use one temporary workspace and explicitly supply job and step environment values. For these examples, the environment-file handoff can accept only the expected literal key and value before constructing the next process environment. Such a narrow model verifies the commands and the stated process relationships. It does not exercise GitHub’s dispatcher, hosted-runner image, token issuer or complete environment-file parser.
Use the documented explicit Bash invocation when comparing failure behavior. GitHub’s syntax reference shows Bash with profile files disabled and -e -o pipefail; an interactive local Bash session can have different settings and startup customization. Passing the happy-path fixture is therefore only a first check. Remove fixture/result.txt before its reader and verify that the command fails under the chosen invocation. Keep that failure separate from inability to start the shell because its working directory does not exist.
Try another mutation: remove the environment-file write but leave the later assertion. The later step should fail because it no longer receives the required result. Replacing that write with export CI_LAB_RESULT=published in the producer should still fail in the next fresh shell. The export-only change shows that export does not transfer a value to a later fresh step. Separately, the existing assertion that CI_LAB_LOCAL is unset catches accidental reuse of the producer’s shell. Removing the write leaves CI_LAB_RESULT unset even in one fresh shared shell; neither mutation makes the complete fixture pass simply through shell reuse.
Finally add a fifth step that prints only the harmless mode and confirms the marker still exists. It should see the job value verify, because the preceding step’s env override was local to that step. If you move the reader into a separate job, do not expect the file to follow it automatically. At that boundary, declare an artifact transfer or regenerate the fixture. A small workflow becomes dependable when each state transition has a named channel and each check runs in the environment the workflow actually requests.