diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs index 3170da16ebd..a18a24f05f2 100644 --- a/docs/astro.config.mjs +++ b/docs/astro.config.mjs @@ -312,6 +312,7 @@ export default defineConfig({ items: [ { label: 'Agentic Authoring', link: '/guides/agentic-authoring/' }, { label: 'Editing Workflows', link: '/guides/editing-workflows/' }, + { label: 'Governance', link: '/guides/governance/' }, { label: 'Reusing Workflows', link: '/guides/reusing-workflows/' }, { label: 'Upgrading Workflows', link: '/guides/upgrading/' }, { label: 'Using MCPs', link: '/guides/mcps/' }, diff --git a/docs/src/content/docs/guides/governance.md b/docs/src/content/docs/guides/governance.md new file mode 100644 index 00000000000..228fa9a0135 --- /dev/null +++ b/docs/src/content/docs/guides/governance.md @@ -0,0 +1,144 @@ +--- +title: Governance +description: Set and manage gh-aw environment defaults across enterprise, organization, and repository scopes with gh aw env. +--- + +# Governance + +Use governance defaults when you want consistent model and +guardrail behavior across many repositories without editing +every workflow file. + +This guide shows how to manage these defaults with +`gh aw env` and how values percolate from enterprise to +organization to repository scope. + +## What `gh aw env` manages + +`gh aw env` manages `GH_AW_DEFAULT_*` variables as GitHub +Actions variables at one scope: + +- repository (`--scope repo`) +- organization (`--scope org`) +- enterprise (`--scope ent`) + +The command uses a YAML file with `default_` keys. + +```yaml title="defaults.yml" +default_max_ai_credits: "5M" +default_max_daily_ai_credits: "15M" +default_max_turns: "12" +default_timeout_minutes: "30" +default_model_copilot: "gpt-5-mini" +default_model_claude: "claude-haiku-4-5" +default_model_codex: "gpt-5.4-mini" +default_detection_model: "gpt-5.5-mini" +default_utc: "-08:00" # UTC offset for rendered CLI timestamps +``` + +> [!NOTE] +> Set a key to `null` (or omit it) to delete that variable +> from the selected scope during `gh aw env update`. + +## Export current defaults + +Start by exporting current values from the target scope. + +```bash +gh aw env get ent-defaults.yml --scope ent --enterprise MY_ENT +gh aw env get org-defaults.yml --scope org --org MY_ORG +gh aw env get repo-defaults.yml --scope repo --repo OWNER/REPO +``` + +## Apply defaults safely + +After editing the YAML file, preview and apply the change. + +```bash +gh aw env update org-defaults.yml --scope org --org MY_ORG --dry-run +gh aw env update org-defaults.yml --scope org --org MY_ORG +``` + +Use `--yes` in automation to skip the interactive +confirmation prompt. + +```bash +gh aw env update org-defaults.yml --scope org --org MY_ORG --yes +``` + +## Governance rollout pattern + +Use a layered rollout to make defaults percolate down: + +1. Set enterprise baseline defaults. +2. Set organization defaults only where needed. +3. Set repository defaults only for true exceptions. +4. Keep workflow frontmatter overrides rare and explicit. + +This keeps most repositories aligned while still allowing +targeted exceptions. + +## How percolation and precedence work + +For values resolved from GitHub Actions `vars.*`, the most +specific scope wins: + +1. workflow frontmatter value (if set) +2. repository variable +3. organization variable +4. enterprise variable +5. built-in compiler fallback + +Examples using this runtime path include +`GH_AW_DEFAULT_MAX_AI_CREDITS`, +`GH_AW_DEFAULT_MAX_DAILY_AI_CREDITS`, +`GH_AW_DEFAULT_DETECTION_MAX_AI_CREDITS`, +and `GH_AW_DEFAULT_MODEL_*`. + +> [!IMPORTANT] +> Some defaults are compile-time values. +> `GH_AW_DEFAULT_MAX_TURNS`, +> `GH_AW_DEFAULT_TIMEOUT_MINUTES`, +> `GH_AW_DEFAULT_MAX_TURN_CACHE_MISSES`, +> `GH_AW_DEFAULT_DETECTION_MODEL`, and +> `GH_AW_DEFAULT_UTC` are read by the compiler process. +> If compilation runs in CI, pass these values into the +> compile step environment. + +```yaml title=".github/workflows/compile.yml" +jobs: + compile: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v5 + - name: Compile workflows + env: + GH_AW_DEFAULT_MAX_TURNS: ${{ vars.GH_AW_DEFAULT_MAX_TURNS }} + GH_AW_DEFAULT_TIMEOUT_MINUTES: ${{ vars.GH_AW_DEFAULT_TIMEOUT_MINUTES }} + GH_AW_DEFAULT_MAX_TURN_CACHE_MISSES: ${{ vars.GH_AW_DEFAULT_MAX_TURN_CACHE_MISSES }} + GH_AW_DEFAULT_DETECTION_MODEL: ${{ vars.GH_AW_DEFAULT_DETECTION_MODEL }} + GH_AW_DEFAULT_UTC: ${{ vars.GH_AW_DEFAULT_UTC }} + run: gh aw compile +``` + +## Troubleshooting + +If `gh aw env update` fails validation: + +- use positive integers for `default_max_turns`, + `default_timeout_minutes`, + `default_max_turn_cache_misses` +- use non-zero integers for + `default_max_ai_credits`, + `default_max_daily_ai_credits`, + `default_detection_max_ai_credits` +- use a numeric UTC offset for `default_utc` + (for example `+00:00` or `-08:00`) +- remove unknown YAML keys + +## Related reference + +- [Environment Variables](/gh-aw/reference/environment-variables/) +- [Compiler Enterprise Environment Controls](/gh-aw/reference/compiler-enterprise-environment-controls/) +- [Cost Management](/gh-aw/reference/cost-management/) +- [Using at Scale in Organizations](/gh-aw/guides/using-at-scale/) diff --git a/docs/src/content/docs/reference/environment-variables.md b/docs/src/content/docs/reference/environment-variables.md index 858a8b70b6b..a3e4c863bc4 100644 --- a/docs/src/content/docs/reference/environment-variables.md +++ b/docs/src/content/docs/reference/environment-variables.md @@ -279,6 +279,7 @@ jobs: ## Related Documentation - [Frontmatter Reference](/gh-aw/reference/frontmatter/) - Complete frontmatter configuration +- [Governance Guide](/gh-aw/guides/governance/) - Roll out and manage defaults across enterprise, organization, and repository scopes - [Safe Outputs](/gh-aw/reference/safe-outputs/) - Safe output environment configuration - [Sandbox](/gh-aw/reference/sandbox/) - Sandbox environment variables - [Compiler Enterprise Environment Controls](/gh-aw/reference/compiler-enterprise-environment-controls/) - Enterprise defaults for timeout, max-turns, detection model, model fallback, and max-ai-credits guardrails