FAQ & Best Practices
Common questions about setting up and running agentic workflows, plus the practices we recommend. Don't see yours? Chat with support.
Getting started
Do I need the Hud SDK installed first?
Yes. Workflows query your production runtime data, so the relevant services must already be instrumented with the Hud SDK and reporting. See Node.js Installation or Python Installation. If a service isn't reporting, the agent will find no functions to analyze.
Where do I get the HUD_MCP_KEY?
HUD_MCP_KEY?From app.hud.io → Settings → API keys. It's a credential that grants read access to your production runtime data, so store it as a repo/workspace secret, never in committed files, and rotate it if it's ever exposed. Where you can, use a separate key per integration.
Which agent / model should I use?
Any of the supported engines. Claude (via the Anthropic API or Bedrock) is the default across the templates; a Codex (OpenAI) GitHub Actions template is also provided. For model choice, use a lighter model (haiku / sonnet) for quick checks and a stronger one (opus) for deep analysis.
How do I authenticate the model provider?
Claude-based runners accept either Anthropic or AWS Bedrock:
| Provider | How |
|---|---|
| Anthropic API | Set ANTHROPIC_API_KEY (from console.anthropic.com). The default. |
| AWS Bedrock | Add AWS credentials, drop the Anthropic key, and set CLAUDE_CODE_USE_BEDROCK: '1', AWS_REGION, and ANTHROPIC_MODEL. |
The Codex runner uses an OpenAI key instead. Full details are in the recipes repo's docs/auth.md.
Do I have to use GitHub?
No. GitHub Actions and gh-aw are GitHub-native, but Cursor automations and Claude routines run independently of any CI. Pick the runner that fits your stack.
Behavior & output
Will these workflows modify my code?
Only the ones designed to. Dead-Code Cleanup and the Weekly Report's optional self-heal open draft pull requests for you to review. Blast Radius and Rollback Check are read-only — they analyze and report, they don't change code.
Are the auto-generated PRs safe to merge automatically?
Treat them as suggestions, not approvals. Self-heal and dead-code PRs open as drafts and should always be human-reviewed before merge — a blast-radius score or rollback verdict is decision support, so keep a human gate on anything irreversible. De-duplication is built in: recipes that open PRs first check for an existing open HUD-labeled PR (and Jira ticket), so re-runs don't pile up duplicates.
Where do the results go?
Wherever you wire the output: a PR comment, a Slack post, a GitHub issue, a draft PR, or a webhook. Each recipe documents its default output, and the runner decides delivery. Scheduled Claude routines run on Anthropic infrastructure rather than your CI, so make sure their output is delivered to a sink you actually watch.
Which environment do workflows query?
Production. The recipes filter on environment_name = 'production' and use SUM(invocations) rather than COUNT(*). If you adapt a prompt, keep those conventions and filter by service_name so queries stay fast. Note that a function with zero invocations in your scope may still be live elsewhere — that's why the Dead-Code recipe checks invocations across all services before flagging anything.
Can I scope a workflow to specific services or teams?
Yes. Use SERVICE_NAMES / HUD_SERVICES to limit scope, and the repo's team-splitting patterns (config file, GitHub Teams, or package.json ownership) to run per-team in a monorepo.
Can I run more than one recipe in a repo?
Yes — add a separate workflow/automation per recipe. They're independent.
Security & permissions
Is it safe to run on pull requests, including from forks?
Several recipes need write access (to comment, label, or open PRs) and access to secrets. On GitHub that means the pull_request_target trigger, which runs in the context of your base branch with secrets available — including for PRs from forks. Best practice:
- Enable PR triggers only on repos with trusted contributors, or guard the job by author association / a maintainer-applied label.
- Never have the agent echo secrets into logs, comments, or PR descriptions.
- Give the workflow least-privilege tokens — only the scopes it needs.
How do I control what the agent can reach over the network?
On gh-aw, an allow-list governs egress. The templates default to defaults, node, github, plus api.hud.io / cdn.hud.io. Add only the domains a recipe actually needs (e.g. slack.com for Slack output) and remove anything unused.
Cost & testing
How much does a run cost?
It depends on the model and the size of the analysis — model tokens are billed by your provider. Multi-phase recipes (like the Weekly Report) and large diffs cost more. To keep it predictable:
- Start with manual runs to measure token usage before scheduling.
- Scope tightly — set
SERVICE_NAMES/HUD_SERVICES, capMAX_FUNCTIONS/MAX_ENDPOINTS, and use a sensibleLOOKBACK_DAYS. - Set timeouts. gh-aw defaults to 30 minutes; raise it only for genuinely long analysis.
- Pick the right model for the job (see above).
How do I test a workflow before automating it?
Run it manually first. Every template includes a manual trigger (workflow_dispatch on Actions/gh-aw, a manual run in Cursor, or invoking the skill directly). Confirm the output looks right before enabling PR or cron triggers.
Privacy
Is my code or data sent anywhere?
The agent runs on your chosen runner and talks to two services: your model provider (Anthropic / Bedrock / OpenAI) for reasoning, and the Hud MCP for runtime data. No third parties beyond those you configure (e.g. Slack, Jira). For Hud's data handling, see PII Scrubbing & Data Collection.
Troubleshooting
The agent reports "no Hud-tracked functions found"
The changed code isn't instrumented or isn't reporting production data. Confirm the service has the Hud SDK installed, is sending data, and that the functions in the diff actually run in production. This is expected (and intentional) for docs-only or config-only PRs.
My scheduled workflow never runs
On GitHub, schedule: triggers only fire on the default branch. Make sure the workflow file is merged to main (not sitting on a feature branch).
The workflow can't connect to Hud / MCP errors
Check that HUD_MCP_KEY is set as a secret and is valid, and that npx -y hud-mcp@v2 can reach api.hud.io (in gh-aw, confirm it's in the network.allowed list). See Troubleshooting MCP Errors.
A Hud query failed mid-run
The recipes retry a failed query once, then abort cleanly without making changes. If you see repeated failures, check that your HUD_MCP_KEY is valid and the services are reporting. On very large PRs, the diff may be truncated — the blast-radius report notes this in its limitations section.
A Slack-output recipe isn't posting
Verify SLACK_BOT_TOKEN has the chat:write (and users:read.email for blame) scopes, that SLACK_CHANNEL is correct, and — on gh-aw — that api.slack.com and slack.com are in the network allow-list.
Re-running the dead-code recipe didn't open a new PR
By design. It skips if an open HUD-labeled PR (or open Jira ticket) already exists for the repo. Close or merge the existing one first.
Where can I see the source?
Everything — recipe prompts, runner templates, and fully worked examples — is open source in the hud-agentic-workflows-recipes repository.