diff --git a/workshop/14-next-steps.md b/workshop/14-next-steps.md index 96fb5ae2..f060260b 100644 --- a/workshop/14-next-steps.md +++ b/workshop/14-next-steps.md @@ -65,6 +65,10 @@ Here's a quick recap of the concepts you've touched. The diagram below shows how - :arrow_right: [Run Your Agentic Workflow on a Self-Hosted Runner](24-self-hosted-runners.md) — target your organisation's runner fleet instead of GitHub-hosted machines (enterprise teams). - :arrow_right: [Audit and Monitor Your Agentic Workflows](25-audit-and-observability.md) — read run artifacts, understand token usage, and build an audit trail for enterprise compliance. - :arrow_right: [Manage Costs and AI Credit Budgets](26-manage-costs-and-budgets.md) — measure AIC consumption, set spending limits, and keep your workflows within budget (enterprise teams). +- :arrow_right: [Verify Your Workflow Quality with Evals](27-evaluate-workflow-quality.md) — add automated YES/NO quality checks so every run tells you whether your workflow met its goal. +- :arrow_right: [Orchestrate Multiple Agentic Workflows](28-orchestrate-workflows.md) — build a coordinator workflow that dispatches specialist workflows based on repository conditions. +- :arrow_right: [Teach Your Agent Domain Knowledge with Skills](29-skills-and-domain-knowledge.md) — encode team conventions in reusable SKILL.md files so your agents always follow house rules. +- :arrow_right: [Govern Your Agentic Workflows with Org-Level Policy Controls](30-governance-and-policy-controls.md) — apply required reviewers, permission scoping, and Actions policies to satisfy enterprise security requirements (enterprise teams). ## ✅ Checkpoint diff --git a/workshop/29-skills-and-domain-knowledge.md b/workshop/29-skills-and-domain-knowledge.md index 42ea3dac..7ae09612 100644 --- a/workshop/29-skills-and-domain-knowledge.md +++ b/workshop/29-skills-and-domain-knowledge.md @@ -143,5 +143,5 @@ Check the compiled `.lock.yml` for the activation step that installs your skill, - [ ] `gh aw compile` succeeded with no unpinned-skill warnings -Want to choose another branch from the workshop hub? Return to [What's Next? Keep Exploring](14-next-steps.md). +**Next:** [Govern Your Agentic Workflows with Org-Level Policy Controls](30-governance-and-policy-controls.md) diff --git a/workshop/30-governance-and-policy-controls.md b/workshop/30-governance-and-policy-controls.md new file mode 100644 index 00000000..2eeb4249 --- /dev/null +++ b/workshop/30-governance-and-policy-controls.md @@ -0,0 +1,132 @@ + + +# Govern Your Agentic Workflows with Org-Level Policy Controls + +> _Enterprise teams need guardrails — policy controls let you define exactly which AI actions are allowed, who must approve deployments, and how to stay compliant across your organisation._ + +## :dart: What You'll Do + +You'll learn how GitHub organisation administrators configure policies for agentic workflows, then apply those policies to your own workflow using `required-reviewers` and permission scoping. By the end, you can describe the governance model to a security team and demonstrate that your workflows respect it. + +## :clipboard: Before You Start + +- You completed [Teach Your Agent Domain Knowledge with Skills](29-skills-and-domain-knowledge.md) or any of the audit and cost management nodes. +- You have Owner or Admin access to the practice organisation, **or** you can read along while your admin demonstrates the settings. +- You understand GitHub Actions [permissions](https://github.github.com/gh-aw/reference/permissions/) and [safe outputs](https://github.github.com/gh-aw/reference/safe-outputs/). + +## Steps + +### Understand the governance model + +Agentic workflows run inside GitHub Actions — which means all Actions governance features apply. On top of that, gh-aw adds a second layer of controls at compile time and at the safe-output declaration level. + +There are three places where an organisation can enforce policy: + +| Layer | Where configured | What it controls | +|---|---|---| +| **GitHub Actions policy** | Organisation → Settings → Actions | Which workflows can run, which runner types are allowed, which external actions can be referenced | +| **gh-aw safe-output allow list** | Workflow frontmatter (`safe-outputs:`) | Which write operations the AI agent is allowed to perform | +| **Required reviewers** | Branch protection rules + environment rules | Who must approve a workflow run before it deploys or writes | + +Understanding all three layers is essential for enterprise teams. The safest workflows use all three together. + +### Review your workflow's safe-output declarations + +Open your `daily-status.md` (or another workflow you built earlier) and read the `safe-outputs:` block in the frontmatter. + +Ask your AI agent to audit it for over-broad permissions: + +```bash +gh copilot +``` + +Then paste: + +```prompt +/agentic-workflows review the safe-outputs block in daily-status.md and flag any declarations that are broader than the workflow strictly needs +``` + +The agent will check whether each declared output type (create-issue, push-to-branch, etc.) is referenced in the task brief, and whether scopes could be narrowed. + +### Add a required-reviewers environment rule + +For workflows that write to production branches or create issues in sensitive repositories, require a human to approve each run. + +In your practice repository, create an Actions environment named `agentic-write`: + +1. Go to your practice repository on GitHub.com. +2. Click **Settings** → **Environments** → **New environment**. +3. Name it `agentic-write` and click **Configure environment**. +4. Under **Required reviewers**, add yourself (or a team). +5. Click **Save protection rules**. + +Now reference that environment in your workflow frontmatter: + +```yaml +--- +on: + workflow_dispatch: + +jobs: + daily-status: + runs-on: ubuntu-latest + environment: agentic-write + permissions: + issues: write + contents: read +--- +``` + +Any run of this workflow will pause and wait for your approval before the agent executes. + +### Narrow permissions to least-privilege + +Review the `permissions:` block. Remove any permission the workflow does not actively use. + +Ask your AI agent to help: + +```bash +gh copilot +``` + +Then paste: + +```prompt +/agentic-workflows update daily-status.md to use the narrowest permissions block that still allows the workflow to create issues and read repository contents +``` + +Compile to confirm no errors: + +```bash +gh aw compile daily-status +``` + +### Check organisation-level Actions policy (admin step) + +> [!NOTE] +> This step requires organisation Owner or Admin access. If you are a participant in a workshop session, your admin will demonstrate this. You can follow along at read-only access. + +In the practice organisation, navigate to **Settings** → **Actions** → **General**. Review: + +- **Actions permissions**: Is the org set to allow only actions from trusted sources? +- **Workflow permissions**: Is the default token set to read-only (recommended)? +- **Fork pull request workflows**: Are workflows from forks blocked from accessing secrets? + +If any of these are set more broadly than necessary, recommend tightening them to your security team. + +### Review the gh-aw governance guide + +Read the [governance guide](https://github.github.com/gh-aw/guides/governance/) for a complete reference on safe-output allow lists, audit trails, and policy enforcement patterns used in enterprise deployments. + +## :white_check_mark: Checkpoint + +- [ ] You can describe the three governance layers (Actions policy, safe-output allow list, required reviewers) and what each controls +- [ ] You added an `environment: agentic-write` rule with at least one required reviewer to your workflow +- [ ] You narrowed the `permissions:` block to the minimum needed for your workflow +- [ ] Your AI agent reviewed the `safe-outputs:` declarations and confirmed no over-broad scopes remain +- [ ] `gh aw compile` succeeded after your frontmatter changes +- [ ] You know where to find the [governance guide](https://github.github.com/gh-aw/guides/governance/) for your security team + + +Want to choose another branch from the workshop hub? Return to [What's Next? Keep Exploring](14-next-steps.md). + diff --git a/workshop/README.md b/workshop/README.md index 4deee13a..b84d7b0b 100644 --- a/workshop/README.md +++ b/workshop/README.md @@ -41,6 +41,7 @@ A hands-on workshop that takes you from zero to a fully automated, AI-powered wo | 27 | [Verify Your Workflow Quality with Evals](27-evaluate-workflow-quality.md) | | 28 | [Orchestrate Multiple Agentic Workflows](28-orchestrate-workflows.md) | | 29 | [Teach Your Agent Domain Knowledge with Skills](29-skills-and-domain-knowledge.md) | +| 30 | [Govern Your Agentic Workflows with Org-Level Policy Controls](30-governance-and-policy-controls.md) | ## Optional Side Quests