Skip to content
agentic-job
This text was generated by an LLM (how cgwalters uses LLMs). cgwalters has not reviewed it yet.

Stable interfaces

This page names what a caller may rely on across releases once 1.0 is cut. Until then nothing is promised, and a 0.x release may change any of it; CHANGELOG.md says what each release changed. From 1.0, a stable interface is removed, renamed or given a different meaning only in a new major version, and a release that deprecates one says so in the changelog first. New optional inputs, keys, types and fields may come in any release.

Everything not named here is internal and may change in any release: the other workflows' and actions' inputs, job and step names, artifact names and their contents (policy.json, summary.json, applied.json and the rest), the agent's brief, the built-in skills, and the agentic-job commands other than through the files below.

The reusable workflow

.github/workflows/agentic-job.yml, called with workflow_call. Its description: fields and workflow.md document each input.

Inputs:

  • the run: id, task, task-artifact, repo, base, kind, outputs, max-outputs, allow, config, context, push-item, proposals-artifact;
  • reviews and events: review, review-task, review-item, event;
  • the agent: agent, model, agent-config-repo, agent-config-ref, agent-config-path, agent-skills, agent-user, github-reads, packages, npm, setup, egress-write-policy, session, idle-minutes;
  • runners and the binary: runner, agent-runner, build-binary;
  • inference: inference-url, inference-register (github-oidc, plain, token-file), inference-audience, inference-token-file;
  • limits: timeout, max-requests, max-tasks, budget-usd;
  • applying: output-repo, item-repo, apply-environment, apply-partial, apply-staged, require-safe-outputs-pat, comment-target, issue, notify, status-comment, title-prefix, branch-prefix, artifact-prefix.

Secrets: SAFE_OUTPUTS_PAT, which a caller should pass explicitly rather than by inherit (the apply job and its token).

Not stable: budget, deprecated in favour of budget-usd; fake-profile, expect-check-refusal and secure-host-image-artifact-id, which exist for this repository's tests; and inference-provider, inference-register: api-key, INFERENCE_API_KEY and MCP_TOKEN, which the workflow accepts and refuses or does not pass on for now (refused for now).

Configuration files

Each is TOML, and a key the binary does not know is refused. A file that uses a key added in a later release is therefore refused by an older pin; from 1.0, a file that works with one release keeps working with the next in the same major version.

  • The bounds file, the workflow's allow input (agentic-job policy --allow, agentic-job event --allow): top-level hosts, allow_http, repos, bases, private, max_outputs, max_patch_bytes, max_patch_files, protected, commit_author, push_repo and dedupe, and the tables [outputs.TYPE], [unprotected_files], [memory], [forge], [secondary_pull_request] and [trigger] (the bounds and the policy, events). allowed_domains is accepted and ignored.
  • The runner configuration, the workflow's config input (agentic-job config --from, sandbox setup --config): the tables [sandbox], [egress], [setup], [inference], [agent], [limits], [session] and [commit] (files read).
  • The secure-host configuration, the action's config input (agentic-job config --host): [sandbox], [egress] and [setup] of the runner configuration, and nothing else (secure-host).

Safe outputs

A run hands back requests in gh-aw's safe-output format: one JSON object a line, its type and that type's fields. The types and their fields are those of gh-aw at the pinned commit, as validation.json records and agentic-job collect checks. On GitHub, apply accepts every type the bounds can allow:

create_pull_request, create_issue, create_discussion, add_comment, close_issue, close_pull_request, add_labels, remove_labels, update_issue, update_pull_request, mark_pull_request_as_ready_for_review, push_to_pull_request_branch, add_reviewer, assign_to_user, link_sub_issue, hide_comment, update_project, create_check_run, create_pull_request_review_comment, reply_to_pull_request_review_comment, resolve_pull_request_review_thread, noop, missing_tool and missing_data.

Off GitHub, agentic-job apply --forge forgejo publishes add_comment and create_pull_request, and refuses the rest (publishing to Forgejo).

Hand-back files

What a producer leaves for run to take (what the agent does):

  • out/safe-outputs.jsonl under the agent's home: the requests above, at most 1 MiB and 1000 lines.
  • out/outcome.json, at most 64 KiB: summary, tests (each a command, exit_code and duration_s), stopped_early (null or why), and checkpoint (complete, done, left, next).

A job other than the agent's hands back through proposals-artifact: an artifact holding outputs.jsonl, and optionally base.json and one aw-BRANCH.patch (proposals from a non-agent job).