GitHub Agentic Workflows Takes Write Access Away From Your AI Agent

The agent proposes, a separate job writes. Here's what to check before you turn it on.

Most of the safety in today's coding agents is a sentence. "Don't push to main." "Only comment, never close issues." "Ask before you delete anything." The agent reads that sentence, and then it holds a token that can do every one of those things anyway.

That gap is fine when you're watching. It stops being fine the moment the agent runs at 3 a.m. because someone opened an issue.

GitHub's answer shipped on October 28, when it made GitHub Agentic Workflows generally available. The interesting part is less the automation than the design choice underneath it: the agent doesn't get to write. It writes a request. A different job, with different permissions, decides whether that request happens.

That flips where your attention should go. In this system the prompt matters less than a short list of settings at the top of the file, and that list is what you should review.

What GitHub Agentic Workflows actually is

GitHub Agentic Workflows (the CLI is called gh aw) is an open source project from GitHub Next (MIT-licensed) that runs coding agents inside GitHub Actions, GitHub's built-in system for running jobs when something happens in a repository.

You write each automation as a Markdown file. The top of the file holds a short block of settings in YAML (called frontmatter): what triggers it, what permissions it has, what tools it can use, and which AI engine runs it. The rest of the file is plain English instructions, like "Analyze this issue and provide helpful triage comments."

Then you run gh aw compile. According to the project README, that command "validates this source and generates the .lock.yml workflow that GitHub Actions executes." You commit both files. The Markdown is the part you edit; the .lock.yml is what actually runs.

The engines it supports are GitHub Copilot, Claude Code, OpenAI Codex, Google Gemini and Pi. GitHub pitches it for work that needs judgment: issue triage, CI failure analysis, documentation updates, test writing. The README is blunt about the boundary: "GitHub Agentic Workflows complements existing CI/CD; it does not replace it." (CI/CD is the automated build, test and deploy pipeline.) Builds, tests and deploys stay in ordinary deterministic workflows.

How the agent loses its pen

Think of the agent as a contractor who can walk through your whole building but can't sign anything. They fill out a request form. Someone at the front desk checks the form, and only then does a clerk with the right stamp file it.

That's close to the real layout. The architecture page describes a chain of separate jobs:

Pre-activation checks roles, permissions and deadlines.
Activation prepares the context, sanitizes the text from the triggering event, and validates the lock file.
Agent runs the AI engine with what the docs call "minimal read-only permissions." Anything it wants to write gets buffered as an artifact instead of sent.
Detection downloads those buffered writes and runs a separate AI analysis for leaked secrets, malicious patches and policy violations. It has no write permissions, and it "must complete successfully and emit a 'safe' verdict" before anything else happens.
Safe output jobs apply the approved writes. Each one has only the permission its action needs: creating an issue gets issues: write, opening a pull request gets contents: write and pull-requests: write.

The agent job also sits behind a network firewall. The Agent Workflow Firewall "uses iptables to redirect HTTP/HTTPS traffic through a Squid proxy container," which in plain terms means every web request the agent makes passes through a gatekeeper that only lets through the domains you list.

So the agent can read your repo, think, and draft. It cannot push, comment, label or merge on its own. Those are separate jobs, each holding one narrow key.

The shift: review the permission list, not the prompt

Here's the idea worth keeping. When the write permission lives in a different job, the prompt stops being your safety mechanism. Your safety mechanism becomes the list of things the agent is allowed to ask for. Put plainly: whatever the prompt says, the agent can only do what its safe outputs allow.

That list is called safe-outputs, and the safe outputs reference shows how specific it gets. A create-issue output can force a title prefix, add fixed labels, and cap the count with max. Other outputs can be restricted to items that already carry a required label or title prefix. Label actions take allowed and blocked patterns, with blocked checked first.

There's a default worth knowing. If you don't write a safe-outputs section at all, the docs say create-issue is turned on with max: 1. So a bare workflow can still open one issue per run. To control that, you write the section yourself.

This is a better question to ask in code review than "is the prompt well written?" A prompt is a wish. A safe-outputs block is a contract the runner enforces. If the block says the agent can only add one comment to issues labeled triage, then a confused or manipulated agent still can't close your release milestone.

It also changes what "dangerous" looks like. The menu of safe outputs is long. It includes creating, updating, closing and merging pull requests, dispatching other workflows, and posting code scanning alerts. A workflow that lists merge in its safe outputs has handed back most of the power the design took away. That's a line you can spot in a diff. It's much harder to spot "the prompt is a little too permissive."

Put this into practice

The quickest way to see the shape is GitHub's own sample. You need the GitHub CLI 2.0.0 or newer, logged in with repo and workflow scopes, and write access to a repository with Actions turned on. The quickstart walks through it:

gh extension install github/gh-aw
gh aw add-wizard githubnext/agentics/repo-status

The wizard asks which engine you want, checks your permissions, sets up the engine secret, and adds the workflow files to .github/workflows/. Each engine wants its own secret: ANTHROPIC_API_KEY for Claude, OPENAI_API_KEY for Codex, GEMINI_API_KEY for Gemini. Copilot is the odd one out: with organization billing it can use the run's own Actions token, and otherwise it wants a separate fine-grained personal access token stored as COPILOT_GITHUB_TOKEN with the "Copilot Requests" permission set to Read.

Run it and watch:

gh aw run repo-status
gh aw status

A successful run opens a status report issue. Then open the Actions tab and look at the run itself. You should see the separate jobs from the list above, and that picture teaches the design faster than any doc.

One detail saves confusion later. The quickstart says to run gh aw compile when you change the frontmatter, and to commit both the .md and the .lock.yml. Treat the frontmatter like code: change it, recompile, review the diff on the lock file.

Before you write your own, it helps to see the settings in one place. Here's a sketch assembled from the documented keys (check each against the docs for your version before you ship it):

---
on:
  issues:
    types: [opened]
permissions:
  contents: read
  issues: read
network:
  firewall: true
  allowed:
    - defaults
safe-outputs:
  add-comment:
    max: 1
---
Read the new issue and post one comment that asks for any missing reproduction steps.

Then use this checklist on every agentic workflow, yours or a template you copied:

permissions: read-only for the agent job. If you see write here, ask why.
safe-outputs: every action listed, each with a max. Anything that merges, closes or dispatches gets a second reviewer.
network.allowed: the shortest domain list that works. The architecture docs show defaults plus ecosystem names like python and node.
threat-detection: the detection job accepts extra steps, and the docs name Semgrep (a code pattern scanner) and TruffleHog (a secret scanner) as examples. If you already run a secret scanner, wire it in here.
Cost: gh aw forecast, out of experimental status at GA, estimates AI credit spend, including the detection job's.

One more move pairs well with this. The same day, GitHub made Actions workflow lockfiles generally available. That's a file at .github/workflows/actions.lock that pins the exact commit of every action your workflows use. A compiled agentic workflow is still an Actions workflow, running on the same runners as your builds. Locking what those runners execute is the cheapest guardrail you can add before the agents arrive.

Honest limitations

Every control is configurable. The README says the security controls can be changed, tells authors to review "permissions, tools, network access, and generated files before deploying," and ends with "Use at your own risk." Good defaults don't survive a template copied without reading.

The detection job is a model too. The scan that approves writes is a prompted AI agent, plus whatever scanners you add. It's a second opinion, not a proof. A clever enough malicious patch could get past both.

Read-only still means read everything. The agent can read your repository and whatever text arrives with the trigger. An issue written by a stranger is input to the agent. Activation sanitizes event text, but read access plus a public issue tracker is still the classic setup for prompt injection, and the agent's reasoning can be steered even if its writes are boxed in.

Check your version. The README says versions from 0.83.3 up to (not including) 0.85.4 were retired pre-emptively after a security vulnerability was found. The advisory explains that a credential used by the pull request safe outputs could end up, decodable, in a downloadable run artifact. Its fix is more than a CLI upgrade: run gh aw upgrade and commit the regenerated .lock.yml files, because the advisory warns that upgrading the CLI alone doesn't replace the pinned action references in existing workflows. The latest release was v1.0.1 when this was written.

It costs credits and licenses. The default Copilot CLI engine needs a Copilot license, per the GA changelog. Other engines bill against your own API key. The detection job spends credits on every run that proposes a write.

Lockfiles don't cover everything either. The gh-actions-lock README lists what it doesn't lock: reusable workflows from other repositories, local ./ actions and container images. And GitHub's own changelog says lockfiles "don't determine whether a dependency is safe."

Where this leaves you

The useful lesson here reaches past GitHub. Any agent setup where the same process thinks and writes leans on the prompt for safety. Splitting those two jobs moves safety into settings you can read in a diff.

If you already run agents in CI, look at one workflow today and answer a single question: which job holds the write token? If the answer is "the one running the model," you know what to change. If you're starting fresh, run the sample, open the Actions tab, and look at the jobs before you read another doc.

Sources: GitHub Agentic Workflows GA changelog (Oct 28, 2026); github/gh-aw README (reviewed at v1.0.1); gh-aw architecture, how it works, quickstart and safe outputs reference; Actions workflow lockfiles GA changelog (Oct 28, 2026); github/gh-actions-lock README (reviewed at 0.4.0).