Skip to content

[docs] Document --push flag safety features (branch validation and user confirmation) #11367

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
pelikhan merged 1 commit into from
Jan 22, 2026
Merged

[docs] Document --push flag safety features (branch validation and user confirmation) #11367

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
56 changes: 38 additions & 18 deletions docs/src/content/docs/setup/cli.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down Expand Up @@ -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.

Expand Down Expand Up @@ -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.

Expand Down