| id | hatch3r-gh-agentic-workflows |
| name | hatch3r-gh-agentic-workflows |
| type | skill |
| description | Sets up CI/CD agentic workflows for continuous AI-powered repository automation (GitHub Actions, Azure Pipelines, GitLab CI) |
| tags | ["devops","ctx:team-only"] |
| quality_charter | agents/shared/quality-charter.md |
| efficiency_patterns | agents/shared/efficiency-patterns.md |
| cache_friendly | true |
CI/CD Agentic Workflows Integration
Platform detection: Check platform in .hatch3r/hatch.json to determine which CI/CD system to use. Defaults to "github".
This skill guides setup for AI-powered CI/CD automation in hatch3r-managed projects. The core SKILL covers GitHub Actions (the default); non-GitHub platforms load on demand from references/.
Step 0 — Detect Ambiguity (P8 B1)
Before any work, scan the invocation for unresolved questions in scope, intent, acceptance criteria, target environment, or irreversibility. If any are found, ask the user via the platform-native question tool per agents/shared/user-question-protocol.md. Do not proceed under silent assumption. Default path, not an exception. Triggers for THIS skill: CI platform (GitHub Actions vs Azure Pipelines vs GitLab CI), AI engine (copilot vs claude vs codex), permission scope (read-only vs write), trigger pattern (schedule vs PR event vs manual), and cost-budget enforcement (token cap vs unbounded).
Fan-out Discipline (P8 B2)
Fan-out scales with task size; token cost never justifies serializing independent work (rules/hatch3r-fan-out-discipline.md P8 B2; agents/shared/efficiency-patterns.md). Emit sub_agents_spawned: { count, rationale, task_structure } in your output.
Progressive Disclosure (Anthropic 2026 skills spec)
| Target platform | File to read |
|---|
| GitHub Actions (default) | This file — read sections below |
| Azure DevOps Pipelines | references/azure-devops.md |
| GitLab CI/CD | references/gitlab-ci.md |
Load only the references file that matches platform in .hatch3r/hatch.json. Do not eagerly load all three.
Overview (GitHub Actions)
GitHub Agentic Workflows (technical preview, Feb 2026) bring AI agent orchestration into GitHub Actions. Agentic Workflows are markdown files in .github/workflows/ with YAML frontmatter that compile to GitHub Actions jobs. They support multiple AI engines (GitHub Copilot, Claude, OpenAI Codex) and use MCP for tool access.
Available Workflow Templates (GitHub)
1. Continuous Test Improvement
Automatically assess test coverage and add high-value tests.
---
name: Continuous Test Improvement
on:
schedule:
- cron: '0 6 * * 1'
workflow_dispatch:
engine: copilot
permissions:
contents: read
pull-requests: write
---
Analyze test coverage gaps and open PRs with new tests for uncovered critical paths.
2. Continuous Triage
Automatically summarize, label, and route new issues.
---
name: Continuous Triage
on:
issues:
types: [opened]
engine: copilot
permissions:
issues: write
---
When a new issue is opened, analyze it, apply labels from the hatch3r taxonomy (type:, priority:, area:*), and add a triage summary comment.
3. Continuous Documentation
Keep documentation aligned with code changes.
---
name: Continuous Documentation
on:
pull_request:
types: [closed]
branches: [{defaultBranch}]
engine: copilot
permissions:
contents: write
pull-requests: write
---
Replace {defaultBranch} with board.defaultBranch from .hatch3r/hatch.json (fallback: "main").
After a PR is merged, check if documentation needs updating and open a follow-up PR.
Security Considerations
- Workflows run in sandboxed environments with minimal permissions
- Use read-only defaults; only grant write permissions when needed
- Review all AI-generated changes before merging
- Network isolation and tool allowlisting are enforced by the runtime
Integration with hatch3r
- hatch3r's label taxonomy (type:, executor:, priority:*) aligns with agentic triage
- The hatch3r-testability (CQ5) agent's patterns can inform continuous testing workflows
- The hatch3r-docs-writer agent's patterns can inform continuous documentation
- Board management commands complement continuous triage
Setup (GitHub)
- Enable GitHub Agentic Workflows in your repository settings
- Create workflow files in
.github/workflows/ using the templates above
- Configure the AI engine (copilot is default, claude and codex are alternatives)
- Set appropriate permissions for each workflow
- Monitor workflow runs in the Actions tab
For Azure DevOps setup: see references/azure-devops.md. For GitLab setup: see references/gitlab-ci.md.
Verification Steps (GitHub)
- Syntax check:
gh workflow view {name} or the Actions web UI
- Dry run:
gh workflow run {name} → gh run watch
- Output review: Check the AI-generated output (PR, comment, label) for quality and correctness.
- Permission audit: Verify the workflow cannot access resources beyond its declared permissions.
- Idempotency: Run the workflow twice on the same input — it should not create duplicate artifacts.
- Error handling: Trigger with invalid/edge-case input — workflow should fail gracefully with clear error.
Platform-equivalent verification for ADO/GitLab: see the platform reference files.
Monitoring (GitHub)
- Execution tracking:
gh run list --workflow={name}
- Failure alerts: Settings → Notifications → Actions
- Cost awareness: Monitor AI token usage per workflow run. Set spending limits in org settings.
- Quality metrics: Track success rate, output acceptance rate (merged PRs / total), mean time per run.
Error Handling
- Workflow file has YAML syntax errors: Validate the workflow file locally before pushing (e.g.,
actionlint for GitHub Actions). Fix all reported errors before committing.
- AI engine produces low-quality or empty output: Add explicit context to the workflow prompt (file references, examples, constraints). If the output is still poor after enrichment, switch to a more capable model.
- Workflow runs exceed cost or time limits: Add
timeout-minutes to the workflow, scope file references to reduce context size, and add concurrency groups to prevent parallel runs.
Troubleshooting
| Symptom | Likely Cause | Fix |
|---|
| Workflow doesn't trigger | Incorrect on: event or branch filter | Verify event type matches, check branch protection rules |
| AI output is empty/poor | Insufficient context in workflow body | Add more context, reference specific files, include examples |
| Permission denied | Missing or insufficient permissions | Add required permissions in frontmatter, check org policies |
| MCP tool fails | Server not available or misconfigured | Verify MCP server is accessible, check auth tokens |
| Rate limiting | Too many workflow runs | Add concurrency groups, reduce trigger frequency |
| Workflow hangs | Large repo context or slow AI response | Set timeout-minutes, scope file references |
Rollback (GitHub)
If a workflow produces undesirable results:
- Disable immediately:
gh workflow disable {name} or toggle in repo Settings → Actions
- Revert outputs: Close AI-generated PRs, remove applied labels, revert merged changes if needed.
- Diagnose:
gh run view {run-id} --log
- Fix and re-enable: Update the workflow file, test via manual dispatch, then re-enable.
Platform-equivalent rollback for ADO/GitLab: see the platform reference files.
Definition of Done
References
- Workflow syntax for GitHub Actions — accessed 2026-05-31, official-docs (GitHub). Source for the
on: triggers, permissions: scoping, workflow_dispatch, and timeout-minutes / concurrency controls in the templates.
- GitHub Agentic Workflows — accessed 2026-05-31, official-docs (GitHub Next). Source for the technical-preview status, markdown-with-frontmatter compile model, and multi-engine (Copilot/Claude/Codex) + MCP tool-access claims in the Overview.
