diff --git a/workshop/14-next-steps.md b/workshop/14-next-steps.md index 96fb5ae2..307c89ad 100644 --- a/workshop/14-next-steps.md +++ b/workshop/14-next-steps.md @@ -65,6 +65,7 @@ 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: [Govern Agentic Workflows Across Your Organisation](30-enterprise-governance.md) — apply org-level permissions, approval gates, and dispatch allowlists to keep automated writes safe at scale (enterprise teams). ## ✅ Checkpoint diff --git a/workshop/26-manage-costs-and-budgets.md b/workshop/26-manage-costs-and-budgets.md index e249d134..d8e780dd 100644 --- a/workshop/26-manage-costs-and-budgets.md +++ b/workshop/26-manage-costs-and-budgets.md @@ -114,5 +114,7 @@ gh aw compile - [ ] You identified at least one technique to reduce token consumption +**Next (enterprise teams):** [Govern Agentic Workflows Across Your Organisation](30-enterprise-governance.md) + Want to choose another branch from the workshop hub? Return to [What's Next? Keep Exploring](14-next-steps.md). diff --git a/workshop/30-enterprise-governance.md b/workshop/30-enterprise-governance.md new file mode 100644 index 00000000..3fca41d7 --- /dev/null +++ b/workshop/30-enterprise-governance.md @@ -0,0 +1,102 @@ + + +# Govern Agentic Workflows Across Your Organisation + +> _Enterprise teams need more than individual workflows — they need guardrails that keep every workflow across every team safe, consistent, and cost-controlled._ + +## :dart: What You'll Do + +You'll apply organisation-level policy controls to agentic workflows: set required permissions, configure dispatch allowlists, and enable approval gates for high-risk writes. By the end, your organisation will have a baseline governance posture for running agentic workflows at scale. + +## :clipboard: Before You Start + +- You have completed [Manage Costs and AI Credit Budgets](26-manage-costs-and-budgets.md) or [Audit and Monitor Your Agentic Workflows](25-audit-and-observability.md). +- You have **Admin** access to a GitHub organisation (GHEC or GHES 3.12+). +- Your organisation has Copilot Enterprise enabled and at least one agentic workflow committed to a repository. + +## Steps + +### Review your workflow's declared permissions + +Every agentic workflow should declare only the scopes it actually uses. Open your `daily-status.md` and confirm the `permissions:` block is minimal: + +```yaml +--- +permissions: + issues: write + contents: read +--- +``` + +Remove any scope you cannot justify. Undeclared scopes default to `read` in most contexts, so listing only what is needed reduces your blast radius if a prompt is misused. + +### Enable organisation-wide required-reviewers for automated writes + +For workflows that write to important branches or create releases, add a required reviewer: + +1. Open your organisation's **Settings** → **Actions** → **General**. +2. Under **Fork pull request workflows**, confirm the approval policy matches your risk appetite. +3. For repositories that hold production configuration, navigate to **Settings** → **Environments**, create an environment called `agentic-writes`, and add at least one required reviewer. +4. In your workflow frontmatter, add the environment declaration: + +```yaml +--- +environment: agentic-writes +permissions: + contents: write +--- +``` + +This adds a manual approval gate. Any workflow run that reaches a write-output step will pause until a reviewer approves it in the Actions UI. + +### Configure a workflow dispatch allowlist + +When workflows dispatch other workflows (as in [Orchestrate Multiple Agentic Workflows](28-orchestrate-workflows.md)), you should limit which workflows are authorised to trigger which others. + +In your orchestrator workflow, verify the `dispatch-workflow` block includes an explicit `workflows` allowlist: + +```yaml +tools: + dispatch-workflow: + workflows: + - daily-status + - pr-reviewer +``` + +Workflows not in this list cannot be triggered by the orchestrator even if the agent asks. This is a compile-time constraint, not a runtime policy, so it is enforced before the agent ever runs. + +> [!TIP] +> Run `gh aw compile --validate` on any orchestrator workflow after editing its allowlist to catch mis-spelled workflow names before they reach production. + +### Review the `gh-aw` governance guide + +The [governance guide](https://github.github.com/gh-aw/guides/governance/) walks through organisation-level settings including: + +- Disabling agentic workflows for specific repositories. +- Requiring code-owner review before a compiled `.lock.yml` can be merged. +- Configuring audit-log streaming to an external SIEM. + +Read the guide's **Policy matrix** table and note which controls require GHES 3.14+ or a GHEC-only setting. + +### Validate your updated workflow + +After any frontmatter change, recompile: + +```bash +gh aw compile +``` + +Check the output for permission or environment warnings. Commit both the updated `.md` and the regenerated `.lock.yml`. + +## :white_check_mark: Checkpoint + +- [ ] Your workflow's `permissions:` block contains only the scopes you can justify +- [ ] You created (or identified an existing) `agentic-writes` environment with at least one required reviewer +- [ ] Your orchestrator workflow's `dispatch-workflow` block includes an explicit `workflows` allowlist +- [ ] `gh aw compile` succeeded with no warnings after your changes +- [ ] You read the governance guide's policy matrix and identified at least one control relevant to your deployment +- [ ] You know which governance controls require a GHES 3.14+ upgrade or a GHEC-only plan + + +Want to explore more enterprise topics? Return to [What's Next? Keep Exploring](14-next-steps.md). + diff --git a/workshop/README.md b/workshop/README.md index 4deee13a..8229f0d2 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 Agentic Workflows Across Your Organisation](30-enterprise-governance.md) | ## Optional Side Quests