From 3e7cd7452de33250f60355b6d0a2408279b9912d Mon Sep 17 00:00:00 2001 From: "Claude Sonnet 4.5" Date: Thu, 22 Jan 2026 18:01:51 +0000 Subject: [PATCH] docs: document --push flag safety features Updates CLI documentation to reflect the safety features added to the --push flag in PR #11343: - Remote repository requirement - Default branch validation - User confirmation prompt (auto-confirmed in CI) Updated documentation for: - gh aw init --push - gh aw run --push - gh aw upgrade --push Co-Authored-By: Claude Sonnet 4.5 --- docs/src/content/docs/setup/cli.md | 56 ++++++++++++++++++++---------- 1 file changed, 38 insertions(+), 18 deletions(-) diff --git a/docs/src/content/docs/setup/cli.md b/docs/src/content/docs/setup/cli.md index 353e6591aa..a94bb2a34c 100644 --- a/docs/src/content/docs/setup/cli.md +++ b/docs/src/content/docs/setup/cli.md @@ -138,11 +138,18 @@ gh aw init --push # Initialize and automatically commit/pu The `--push` flag automatically commits and pushes initialization changes to the remote repository: -1. **Pre-check**: Validates working directory is clean before starting -2. **Initialization**: Runs normal init process -3. **Automatic commit**: Stages all changes with commit message "chore: initialize agentic workflows" -4. **Pull and push**: Pulls latest changes with rebase, then pushes to remote -5. **Graceful fallback**: If no remote is configured (local testing), commits locally only +1. **Remote check**: Requires a remote repository to be configured +2. **Branch validation**: Verifies current branch matches repository default branch +3. **User confirmation**: Prompts for confirmation before committing/pushing (skipped in CI) +4. **Pre-check**: Validates working directory is clean before starting +5. **Initialization**: Runs normal init process +6. **Automatic commit**: Stages all changes with commit message "chore: initialize agentic workflows" +7. **Pull and push**: Pulls latest changes with rebase, then pushes to remote + +Safety features: +- Prevents accidental pushes to non-default branches +- Requires explicit user confirmation outside CI environments +- Auto-confirms in CI (detected via `CI`, `CONTINUOUS_INTEGRATION`, `GITHUB_ACTIONS` env vars) When used, requires a clean working directory (no uncommitted changes) before starting. @@ -271,13 +278,19 @@ gh aw run workflow --push --ref main # Push to specific branch The `--push` flag automatically handles workflow updates before execution: -1. **Auto-recompilation**: Detects when `.lock.yml` is outdated and recompiles workflow -2. **Transitive imports**: Collects and stages all imported files recursively -3. **Confirmation prompt**: Interactive confirmation dialog before commit -4. **Smart staging**: Stages workflow `.md` and `.lock.yml` files plus dependencies -5. **Automatic commit**: Creates commit with message "Updated agentic workflow" -6. **Branch validation**: Verifies specified branch with `--ref` exists before pushing -7. **Workflow dispatch**: Triggers workflow run after successful push +1. **Remote check**: Requires a remote repository to be configured +2. **Branch validation**: Verifies current branch matches repository default branch (or branch specified with `--ref`) +3. **User confirmation**: Prompts for confirmation before committing/pushing (skipped in CI) +4. **Auto-recompilation**: Detects when `.lock.yml` is outdated and recompiles workflow +5. **Transitive imports**: Collects and stages all imported files recursively +6. **Smart staging**: Stages workflow `.md` and `.lock.yml` files plus dependencies +7. **Automatic commit**: Creates commit with message "Updated agentic workflow" +8. **Workflow dispatch**: Triggers workflow run after successful push + +Safety features: +- Prevents accidental pushes to non-default branches (unless explicitly specified with `--ref`) +- Requires explicit user confirmation outside CI environments +- Auto-confirms in CI (detected via `CI`, `CONTINUOUS_INTEGRATION`, `GITHUB_ACTIONS` env vars) When `--push` is not used, warnings are displayed for missing or outdated lock files. @@ -411,12 +424,19 @@ gh aw upgrade --push --no-fix # Update agent files and push The `--push` flag automatically commits and pushes upgrade changes to the remote repository: -1. **Pre-check**: Validates working directory is clean before starting -2. **Version check**: Ensures gh-aw extension is on latest version -3. **Upgrade process**: Updates agent files, applies codemods, and recompiles workflows -4. **Automatic commit**: Stages all changes with commit message "chore: upgrade agentic workflows" -5. **Pull and push**: Pulls latest changes with rebase, then pushes to remote -6. **Graceful fallback**: If no remote is configured (local testing), commits locally only +1. **Remote check**: Requires a remote repository to be configured +2. **Branch validation**: Verifies current branch matches repository default branch +3. **User confirmation**: Prompts for confirmation before committing/pushing (skipped in CI) +4. **Pre-check**: Validates working directory is clean before starting +5. **Version check**: Ensures gh-aw extension is on latest version +6. **Upgrade process**: Updates agent files, applies codemods, and recompiles workflows +7. **Automatic commit**: Stages all changes with commit message "chore: upgrade agentic workflows" +8. **Pull and push**: Pulls latest changes with rebase, then pushes to remote + +Safety features: +- Prevents accidental pushes to non-default branches +- Requires explicit user confirmation outside CI environments +- Auto-confirms in CI (detected via `CI`, `CONTINUOUS_INTEGRATION`, `GITHUB_ACTIONS` env vars) When used, requires a clean working directory (no uncommitted changes) before starting.