GitHub agentic workflows, and the open-source row with no compile step

What the compile step turns a markdown file into

GitHub Agentic Workflows is GitHub's product for "AI-powered repository automations that you define in markdown and run as GitHub Actions workflows". One workflow is a markdown file with YAML frontmatter on top: triggers, permissions, safe outputs. The body under the frontmatter is the instruction set the agent reads. gh aw compile takes that file and writes "a hardened, pinned Actions workflow", a .lock.yml, which is committed and pushed to the default branch and then runs like any Actions workflow, on its trigger or by hand.

Three things have to be in place before the first run. Actions must be enabled for the repository. An AI engine account must have its secret configured, and the engine can be GitHub Copilot, Anthropic Claude, OpenAI Codex or Google Gemini. The GitHub CLI must be installed. Copilot is the default engine. The gh aw project is open source, so the compiler is code you can read.

The permission model is the part worth reading twice. Agents run read-only by default, a write goes through a declared "safe output", and a separate job applies it after a separate threat-detection step has scanned what the agent proposed. The agent never holds the token that writes.

That model is also the constraint. gh aw compile is what makes a GitHub agentic workflow safe, and it is what fixes the workflow's whole scope to an Actions job over a repository. What an agentic workflow is in the general sense is a goal handed to a model that chooses the steps; the compile step decides where that model may stand while it chooses.

What the frontmatter declares, and what GitHub bounds

The frontmatter is where a workflow declares its own scope. GitHub's docs describe it as configuring "when the workflow runs, what permissions it has, and what write operations are allowed", and gh aw compile is what turns those declarations into a .lock.yml that may run: the schema is validated, expressions are allowlisted, actions are pinned, and the file is committed to the default branch. That compiled file is the whole set of permissions, pinned actions and declared writes the job may use; by default the agent reads the repository, the issue or pull request and the CI logs, and a declared web-search, web-fetch, Playwright or MCP server widens what it can read.

Three bounds set where the job can run, and all three come from GitHub.

The trigger has to be an event GitHub can raise: a schedule, a push, an issue, a pull request, a comment, or a hand dispatch. A job that should start when a supplier emails an invoice needs something outside GitHub to turn that email into a repository event first. The trigger sets the boundary of what a workflow can notice at all.

Cost arrives as Actions minutes plus inference, and inference is metered in AI Credits at "1 AIC = $0.01 USD". Both caps are frontmatter keys and they behave differently. max-ai-credits bounds one run, 1,000 AIC by default: gh-aw calls it "a hard stop for unusually expensive runs" and "emits steering warnings before the run reaches the limit", so the run is already going when it stops at the cap, and a run stopped at the cap is what the log shows. max-daily-ai-credits bounds a workflow across 24 hours, 5,000 AIC by default: when the total from the past 24 hours exceeds the threshold, activation reports the exceeded budget and "skips the agent job", leaving the conclusion job to report the failure context. The home page's "Over budget, the agent is skipped" describes that daily key. Two commands read the bill afterwards: gh aw logs lists tokens, AIC and turns per run, and gh aw audit <run-id> breaks a single run down.

A write lands where its declared safe output says. A repository change arrives as a commit on a branch and a pull request, and "Review generated changes before merging" is the instruction for it: the diff sits beside the issue that caused it, and the reviewer already has the repo open. Triage, a CI investigation and a daily report arrive as an issue or a comment. GitHub's own CI Doctor workflow "opens an issue with the likely root cause", and the daily status report is posted as an issue. The review happens wherever the output lands, so a workflow that files issues is read by whoever watches the tracker, not by a merge button.

That is the scope the compile step sets. The safe outputs in the frontmatter are the list of writes the run may ask for, and the separate job that applies them holds the credentials the agent never sees.

The same job in a file that is never compiled

A Kortix workflow is a trigger row in kortix.yaml, in the project repository, beside the agents it starts. Nothing compiles it. The file is the workflow: kortix ship validates it, commits it and pushes it, and the row fires from there.

The daily-digest example shows the two parts that decide what a run can do: the agents: entry with its two keys, and the trigger row whose on: holds a six-field cron and an IANA timezone. Further down the same file, a run: names the agent and the prompt that becomes the session's first message. The two keys under the agent decide whether the run can read the repository and propose a change, and both default off.

workspace.project_repository is false until you set it. true checks the project repository out in /workspace, which is where a digest reads yesterday's commits from. kortix_permissions defaults to none, and opening a change request needs project.gitops.push. A manifest with an agent, a prompt and neither key starts on time, thinks, and then finds no repository and no way to propose the file it wrote. That pair is the difference between a demo and a workflow, and it is two lines. The build walkthrough takes the row from the first line to the merged change request.

kortix triggers fire daily-digest runs it by hand, now, without waiting for the clock. The session boots its own machine from the sandbox image the project declares, clones the repo into /workspace and cuts a branch. One isolated sandbox per session. Each session has its own isolated machine and branch. The agent writes digests/YYYY-MM-DD.md, commits it and opens a change request with kortix cr open --title "Daily digest". Session work reaches main through a change request. Merge is default-deny for agents.

Before any of that, the row has to parse. python3 scripts/check_workflow.py examples/*/kortix.yaml reads each manifest offline and prints one line per file and a total:

ok   examples/daily-digest/kortix.yaml  (1 trigger(s), 1 agent(s))
2 manifest(s) ok.

The checker looks for the mistakes a hand-written row makes: a cron with five fields instead of six, a timezone that is not an IANA name, a webhook secret that env does not declare, a run.session value outside the four, an agent name that is not declared, a type beside on:, and a kortix_version line the format no longer takes. A broken file prints FAIL and one line per rule it broke. After the run, the machine stops about 15 to 20 minutes after the last turn and keeps /workspace, the branch and the conversation.

Which shape fits the job

The test is what a compiled workflow can express. A .lock.yml is an Actions job with a pinned action set, a permission list and the safe outputs the frontmatter declares, all checked before the first run.

If the job's result is one of those writes, GitHub's product is the better pick, and it is good at these. Triage, a CI failure investigation, a docs update, a test that should exist, a dependency bump: the trigger is already a GitHub event, the output lands as an issue, a comment or a pull request, and the AI Credit bill joins the rest of Actions on one invoice. Nothing has to move for the workflow to fit, and the compile step is an asset here.

The boundary shows up when the result is not one of those writes. The agent's token is read-only by default and the credentials that can write sit in the separate job that applies the declared outputs, so a write the frontmatter did not name has no job to apply it. That work needs a machine of its own, with the connector on it and a sandbox it can install into, while the part that does belong in the repo still needs a branch.

A Kortix trigger row starts that machine. One isolated sandbox per session. Each session has its own isolated machine and branch, booted from the sandbox image the project declares, with the connectors the agent names. Session work reaches main through a change request. Merge is default-deny for agents, so the part that belongs in the repo still ends in a diff a person can refuse, and the rest happens on the machine that holds the connector. Run it on Kortix Cloud, in your VPC, or on your own on-prem network. Self-host is free. Worked examples and agentic workflow tools cover the rest of the field.