From b3a95386a1c4e5d151fe6b8d3fbfd97a99439633 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Mon, 23 Feb 2026 04:24:01 +0000 Subject: [PATCH] docs: add private: frontmatter field documentation (#17801) Documents the new `private: true` frontmatter field that prevents workflows from being installed into other repositories via `gh aw add`. - Adds Private Workflows section to frontmatter reference - Adds note about private workflows to the packaging/imports guide Co-Authored-By: Claude Sonnet 4.6 --- .../content/docs/guides/packaging-imports.md | 3 +++ .../src/content/docs/reference/frontmatter.md | 19 +++++++++++++++++++ 2 files changed, 22 insertions(+) diff --git a/docs/src/content/docs/guides/packaging-imports.md b/docs/src/content/docs/guides/packaging-imports.md index 12c14971aba..d34c952eab9 100644 --- a/docs/src/content/docs/guides/packaging-imports.md +++ b/docs/src/content/docs/guides/packaging-imports.md @@ -40,6 +40,9 @@ Use `--name`, `--pr`, `--force`, `--engine`, or `--verbose` flags to customize i > [!NOTE] > Check carefully that the workflow comes from a trusted source and is appropriate for your use in your repository. Review the workflow's content and understand what it does before adding it to your repository. +> [!NOTE] +> Workflows marked with `private: true` in their frontmatter cannot be added to other repositories. Attempting to do so will fail with an error. See [Private Workflows](/gh-aw/reference/frontmatter/#private-workflows-private) for details. + ## Updating Workflows When you add a workflow, a tracking `source:` entry remembers where it came from. You can keep workflows synchronized with their source repositories: diff --git a/docs/src/content/docs/reference/frontmatter.md b/docs/src/content/docs/reference/frontmatter.md index 927c2993a06..6760d1e9825 100644 --- a/docs/src/content/docs/reference/frontmatter.md +++ b/docs/src/content/docs/reference/frontmatter.md @@ -54,6 +54,25 @@ Tracks workflow origin in format `owner/repo/path@ref`. Automatically populated source: "githubnext/agentics/workflows/ci-doctor.md@v1.0.0" ``` +### Private Workflows (`private:`) + +Mark a workflow as private to prevent it from being installed into other repositories via `gh aw add`. + +```yaml wrap +private: true +``` + +When `private: true` is set, attempting to add the workflow from another repository will fail with an error: + +``` +workflow 'owner/repo/internal-tooling' is private and cannot be added to other repositories +``` + +Use this field for internal tooling, sensitive automation, or workflows that depend on repository-specific context and are not intended for external reuse. + +> [!NOTE] +> The `private:` field only blocks installation via `gh aw add`. It does not affect the visibility of the workflow file itself — that is controlled by your repository's access settings. + ### Labels (`labels:`) Optional array of strings for categorizing and organizing workflows. Labels are displayed in `gh aw status` command output and can be filtered using the `--label` flag.