GitHub Agentic Workflows

DATS uses GitHub Agentic Workflows (gh-aw) for AI-powered repository automation. These workflows run on GitHub-hosted runners and are separate from the self-hosted runner fleet described in Configure GitHub Action Runners.

How agentic workflows work

An agentic workflow has two committed files under .github/workflows/:

<name>.md is the source maintained by developers. YAML frontmatter configures its trigger, permissions, engine, tools, network access, and safe outputs; the Markdown body is the agent prompt.
<name>.lock.yml is the generated GitHub Actions workflow executed by GitHub. Do not edit it manually.

Both files must be committed together. The lock file contains hashes of the source frontmatter and prompt. GitHub rejects an outdated lock file, so every source change must be followed by compilation.

The agent itself receives read-only GitHub permissions. Mutations such as updating a pull request or adding a comment are declared through safe-outputs; gh-aw validates the requested output and applies it in a separate, permission-controlled job.

For example, the PR overview workflow is maintained in agent-pr-overview.md, with the generated workflow in agent-pr-overview.lock.yml.

Install the CLI extension

Install and authenticate the GitHub CLI, then install the gh-aw extension:

gh auth status
gh extension install github/gh-aw
gh aw version

Upgrade an existing installation before creating or substantially updating a workflow:

gh extension upgrade aw

If extension installation encounters authentication problems, use the official installation script.

Create a workflow

When asking a coding agent to create or update a workflow, give it the official gh-aw creation instructions. Those instructions route the task to the detailed gh-aw workflow designer and require the relevant references to be read before files are changed.

A new workflow should be added as .github/workflows/<name>.md. Keep the agent job read-only, enable only the required toolsets, and route every GitHub mutation through safe-outputs.

Compile the workflow from the repository root:

gh aw compile <name> --strict
gh aw compile <name> --validate

If compilation requests approval for a newly referenced secret, review the secret name and compile with:

gh aw compile <name> --strict --approve

Review and commit both resulting files:

.github/workflows/<name>.md
.github/workflows/<name>.lock.yml

Generated lock files are intentionally tracked and marked as generated through .gitattributes.

Minimize agent access

Every workflow must follow least privilege: give the agent only the tools, GitHub data, repository permissions, and network access required for its stated task. Extra capabilities increase the impact of a mistaken or manipulated tool call and make the workflow harder to review.

Apply this rule across the complete workflow configuration:

Select the smallest GitHub toolsets list that covers the required reads. Do not use default or all merely for convenience.
Match permissions to those toolsets, using read access only. For example, repos generally needs contents: read, issues needs issues: read, and pull_requests needs pull-requests: read.
Restrict bash to the commands the task actually needs. An empty list disables shell commands entirely.
Set edit: false when the agent does not need to modify files.
Declare only the required safe-outputs. These are the controlled write operations available after agent execution; they do not require direct write permission in the agent job.
Allow only required network destinations. Network access is a separate capability and should not be broader than the configured tools and engine require.
For custom MCP servers, restrict their allowed tools instead of exposing the server's complete API.

For example, a PR reporting workflow that reads repository files and PR conversations but never edits the checkout can use:

permissions:
  contents: read
  issues: read
  pull-requests: read
tools:
  github:
    mode: gh-proxy
    toolsets: [repos, issues, pull_requests]
  bash: [cat, find, grep, head, sed, tail, wc]
  edit: false
safe-outputs:
  add-comment:
    pull-requests: true

Tool availability and configuration are documented in two places:

The tools reference lists built-in tools such as bash, edit, web access, Playwright, memory, and custom MCP integrations.
The GitHub tools reference lists the available GitHub toolsets and the individual-tool allowed option. Common toolsets include repos, issues, pull_requests, and actions; consult the reference instead of assuming the list is stable.

After choosing the tools, compile in strict mode and inspect the configured MCP tools:

gh aw compile <name> --strict
gh aw mcp inspect <name>

Review tool access again whenever the workflow's prompt or responsibilities change. Remove capabilities that are no longer used.

Update an existing workflow

Edit only .github/workflows/<name>.md.
Run gh aw compile <name> --strict.
Run gh aw compile <name> --validate.
Review changes to both the Markdown source and lock file.
Commit and push both files together.

If an Actions run reports CONFIG_HASH_MISMATCH, the committed lock file does not correspond to the committed Markdown source. Recompile and commit the regenerated lock file.

BYOK engine configuration

The Copilot engine can run in bring-your-own-key (BYOK) mode. Here, Copilot is the agent harness managed by gh-aw, while inference is routed to a configured external model provider. Provider settings belong in GitHub repository settings.

Configure the following under Settings → Secrets and variables → Actions.

Repository variables:

Variable	Value
`COPILOT_PROVIDER_BASE_URL`	The provider's base URL, such as `https://llm-provider.example.com/v1`
`COPILOT_PROVIDER_TYPE`	`openai`
`COPILOT_PROVIDER_WIRE_API`	The API supported by the selected model, such as `responses` or `completions`
`COPILOT_MODEL`	The model identifier exposed by the provider

Repository secret:

Secret	Value
`COPILOT_PROVIDER_API_KEY`	The model provider API key

Never store the API key as a repository variable or commit it to a workflow. GitHub variables are not secret.

The workflow's network allowlist is compiled into the lock file. The concrete provider hostname must be allowed when the base URL comes from a GitHub variable. Changing the provider hostname therefore requires updating the Markdown workflow and recompiling it.

Custom or private models may not be present in gh-aw's public pricing catalog. Register each selected model under models.providers.github-copilot with its input and output costs so gh-aw can enforce AI-credit limits. Use zero rates only for a model with no direct per-token charge. When COPILOT_MODEL changes to an unregistered identifier, add its pricing entry and recompile the workflow. See custom model pricing for the schema and units.

models:
  providers:
    github-copilot:
      models:
        moonshotai/Kimi-K3:
          cost:
            input: "0"
            output: "0"

Running and debugging

Agentic workflows appear in the repository's Actions tab like other GitHub Actions workflows. Useful commands include:

gh aw status
gh aw run <name>
gh aw logs <name>
gh aw audit <run-id>

Use the gh-aw debugging instructions when investigating a failed or unexpected run.