Text of github.github.com › gh-aw › reference › steps-jobs as Styx crawled it on Nov 19, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

Custom Steps and Jobs | GitHub Agentic Workflows

Skip to main content Custom Steps and Jobs Custom steps and jobs let you mix deterministic computation with agentic execution. All custom steps and jobs run outside the firewall sandbox with standard GitHub Actions security. See DeterministicOps for patterns combining computation with AI reasoning. Choosing the Right Step Hook Section titled “Choosing the Right Step Hook” Use these top-level step hooks in this order: pre-steps: — runs before checkout and all later built-in agent-job setup; only compiler-injected OTLP masking steps may run earlier.

Use this for short-lived token minting or anything that must happen before repository checkout. steps: — runs after checkout and the normal runtime/bootstrap steps, but before the final pre-agent phase. Use this for deterministic preprocessing that needs the checked-out repository. pre-agent-steps: — runs after framework-owned initialization such as checkout cleanup and base-branch restoration, and before MCP startup and engine execution.

Use this for last-moment environment preparation immediately before the agent starts. post-steps: — runs after the engine finishes. Use this for cleanup, summaries, uploads, or follow-up automation. Custom Pre-Checkout Steps ( pre-steps: ) Section titled “Custom Pre-Checkout Steps (pre-steps:)” Add custom steps before checkout and the later pre-checkout agent-job setup. Compiler-injected OTLP masking steps may still run earlier. pre-steps : - name : Mint checkout token id : checkout_app uses : actions/create-github-app-token@v2 with : app-id : ${{ vars.APP_ID }} private-key : ${{ secrets.APP_PRIVATE_KEY }} repositories : ${{ github.repository }} permission-contents : read Set an explicit repositories input and permission-* inputs for every actions/create-github-app-token step; otherwise the installation token can inherit access across the App installation.

To scope a token to the current repository, use repositories: ${{ github.repository }} . The action accepts the fully qualified owner/repository value from this trusted context. If you set owner to a different installation owner, explicitly list repositories belonging to that owner instead. The compiler warns when either is missing and rejects the workflow in strict mode. Job-level permissions: does not scope the App token.

Use pre-steps when later checkout or setup must consume outputs from a step in the same job. For compiler-managed token wiring, give the official actions/create-github-app-token action the reserved id: create-token . The compiler recognizes only that action with this ID; third-party and similarly named actions do not trigger token wiring or automatic OIDC permissions. It prefers the step’s output for compiler-owned default GitHub token bindings that run later in the same generated job.

Authored step environments and explicitly configured credentials are left unchanged. The compiler also adds id-token: write to the minting job unless id-token: none is explicitly configured or safe-outputs.id-token: none disables automatic grants. permissions : contents : read id-token : write pre-steps : - name : Retrieve centrally managed GitHub credential id : plugin_credentials uses : octo-org/central-credentials-action@0123456789abcdef0123456789abcdef01234567 plugins : - plugin : octo-org/private-agent-plugin@0123456789abcdef0123456789abcdef01234567 github-token : ${{ steps.plugin_credentials.outputs.github_token }} pre-steps and Agent Plugin checkout run in the same generated agent job, so plugin auth can use ${{ steps.<id>.outputs.<name> }} (or ${{ env.<name> }} when an action exports credentials through $GITHUB_ENV ). ${{ needs.<job>.outputs.<name> }} crosses a job boundary and may be unsuitable for masked credentials.

Custom Steps ( steps: ) Section titled “Custom Steps (steps:)” Add custom steps before agentic execution. If unspecified, a default checkout step is added automatically. steps : - name : Install dependencies run : npm ci Use custom steps to precompute data, filter triggers, or prepare context for AI agents. Steps can also short-circuit the agent by writing a noop entry to $GH_AW_SAFE_OUTPUTS — the harness detects this at startup and exits cleanly without incurring any AI inference cost.

See Skip the Agent When It Is Not Needed for details. See Checkout and Host Step Order for checkout ordering, untrusted-ref warnings, and safe handling of fetched refs. Custom Pre-Agent Steps ( pre-agent-steps: ) Section titled “Custom Pre-Agent Steps (pre-agent-steps:)” Add custom steps before MCP gateway startup in the agent job so prerequisite MCP installation/configuration can happen first. pre-agent-steps : - name : Finalize Context run : ./scripts/prepare-agent-context.sh Use pre-agent steps when work must happen right before the engine runs (for example, final context preparation or last-moment validations).

Custom Post-Execution Steps ( post-steps: ) Section titled “Custom Post-Execution Steps (post-steps:)” Add custom steps after agentic execution. Run after the AI engine completes regardless of success/failure (unless conditional expressions are used). post-steps : - name : Upload Results if : always() uses : actions/upload-artifact@v4 with : name : workflow-results path : /tmp/gh-aw/agent/ retention-days : 7 Useful for artifact uploads, summaries, cleanup, or triggering downstream workflows.

Post-steps must not create issues directly, read safe-output files, or expose secrets through a step-level env section. Avoid uploading the entire /tmp/gh-aw/ directory, which can contain protected safe-output files. Use safe-outputs.create-issue to publish agent-generated issues instead. Custom Jobs ( jobs: ) Section titled “Custom Jobs (jobs:)” Define custom jobs that run before agentic execution. The agentic execution job waits for all custom jobs to complete.

Custom jobs can share data with the agent through artifacts or job outputs. To run a custom job after agentic execution, add needs: [agent, detection] (or needs: detection if agent outputs are not referenced directly). The compiler also recognizes transitive post-agent dependencies. When detection is enabled, every downstream custom job receives a direct detection dependency and a non-overridable success guard. Failed, cancelled, skipped, missing, or warn-mode flagged detection results block the custom job, including reusable workflow calls and jobs using if: always() .

Custom jobs cannot run between agent and detection. Explicitly disabling detection removes this gate. For notifications that must run even when detection fails or flags warn-mode findings, mark a leaf custom job detection-gate: status-only : jobs : status : needs : [ agent , detection , safe_outputs ] detection-gate : status-only if : always() runs-on : ubuntu-latest steps : - run : echo "${{ needs.agent.result }} ${{ needs.detection.result }} ${{ needs.safe_outputs.outputs.created_issue_number }}" The compiler adds detection to needs if needed and preserves the authored if .

The job may read outputs from detection-gated compiler-owned jobs (such as safe_outputs ) and authored custom jobs that the dependency graph proves run before agent , with no direct or transitive dependency on agent or detection . This allows a reporter to use pre-agent metadata, such as a validated PR number and head SHA, even when detection fails. Declare each metadata job as a direct dependency in the reporter’s needs , then pass its outputs through env ; do not interpolate custom outputs directly into run or actions/github-script code.

The compiler rejects the opt-out if the job downloads artifacts, calls an opaque reusable workflow, reads other job outputs, or references GH_AW_AGENT_OUTPUT or agent/safe-output files in env or run . Other custom jobs cannot depend on a job using this option. The detection-gate key is compiler-only and is not emitted in the Actions workflow. See Custom job detection gates . jobs : super_linter : runs-on : ubuntu-latest steps : - uses : actions/c

The rest of this page is on the live site.