Merge branch 'main' into campaign-orchestrator

Author: mnkiefer

.github/aw/github-agentic-workflows.md

@@ -108,6 +108,8 @@ jobs:
 
       - name: Test full install script (without dummy version)
         shell: bash
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: |
           chmod +x install-gh-aw.sh
           

.github/workflows/install.yml

@@ -216,6 +216,11 @@ on:
     names: []
       # Array items: Label name
 
+    # Whether to lock the issue for the agent when the workflow runs (prevents
+    # concurrent modifications)
+    # (optional)
+    lock-for-agent: true
+
   # Issue comment event trigger
   # (optional)
   issue_comment:

docs/src/content/docs/reference/frontmatter-full.md

@@ -195,6 +195,22 @@ The process of checking workflow files for errors, security issues, and best pra
 ### Cache Memory
 Persistent storage for workflows that preserves data between runs. Configured using `cache-memory:` in the tools section, it enables workflows to remember information and build on previous interactions.
 
+### Campaign
+A finite, enterprise-scale initiative with explicit ownership, approval gates, and executive visibility. Campaigns orchestrate business outcomes (security remediation, dependency updates, compliance enforcement) across multiple repositories with governance, accountability, and ROI tracking. Unlike regular workflows that execute operations, campaigns manage business initiatives with measurable outcomes, defined budgets, stakeholder reporting, and compliance audit trails.
+
+**Key characteristics:**
+- Finite duration (days to months) with clear start and end
+- Named owners and executive sponsors
+- Formal approval gates and change control
+- Budget tracking with ROI metrics
+- Stateful execution using repo-memory for audit trails
+- Cross-team and cross-repository coordination
+- Executive dashboards and KPI reporting
+
+**File naming:** Use `.campaign.md` extension (e.g., `security-compliance.campaign.md`)
+
+See the [Campaigns Guide](/gh-aw/guides/campaigns/) for implementation patterns and examples.
+
 ### Command Triggers
 Special triggers that respond to slash commands in issue and PR comments (e.g., `/review`, `/deploy`). Configured using the `command:` section with a command name.
 

docs/src/content/docs/reference/glossary.md

@@ -3,7 +3,8 @@
 # Script to download and install gh-aw binary for the current OS and architecture
 # Supports: Linux, macOS (Darwin), FreeBSD, Windows (Git Bash/MSYS/Cygwin)
 # Usage: ./install-gh-aw.sh [version]
-# If no version is specified, it will use the latest release
+# If no version is specified, it will fetch and use the latest release
+# Example: ./install-gh-aw.sh v1.0.0
 
 set -e  # Exit on any error
 
@@ -109,48 +110,72 @@ print_info "Detected OS: $OS -> $OS_NAME"
 print_info "Detected architecture: $ARCH -> $ARCH_NAME"
 print_info "Platform: $PLATFORM"
 
-# Function to fetch release data with fallback for invalid token
+# Function to fetch release data with fallback for invalid token and retry logic
 fetch_release_data() {
     local url=$1
+    local max_retries=3
+    local retry_delay=2
     local use_auth=false
-    local curl_args=("-s" "-f")
 
     # Try with authentication if GH_TOKEN is set
     if [ -n "$GH_TOKEN" ]; then
         use_auth=true
-        curl_args+=("-H" "Authorization: Bearer $GH_TOKEN")
     fi
 
-    # Make the API call
-    local response
-    response=$(curl "${curl_args[@]}" "$url" 2>/dev/null)
-    local exit_code=$?
-    
-    # If the call failed and we used authentication, try again without it
-    if [ $exit_code -ne 0 ] && [ "$use_auth" = true ]; then
-        print_warning "API call with GH_TOKEN failed. Retrying without authentication..."
-        print_warning "Your GH_TOKEN may be incompatible (typically SSO) with this request."
-        response=$(curl -s -f "$url" 2>/dev/null)
-        exit_code=$?
-    fi
-    
-    if [ $exit_code -ne 0 ]; then
-        return 1
-    fi
+    # Retry loop
+    for attempt in $(seq 1 $max_retries); do
+        local curl_args=("-s" "-f")
+        
+        # Add auth header if using authentication
+        if [ "$use_auth" = true ]; then
+            curl_args+=("-H" "Authorization: Bearer $GH_TOKEN")
+        fi
+        
+        print_info "Fetching release data (attempt $attempt/$max_retries)..." >&2
+        
+        # Make the API call
+        local response
+        response=$(curl "${curl_args[@]}" "$url" 2>/dev/null)
+        local exit_code=$?
+        
+        # Success
+        if [ $exit_code -eq 0 ] && [ -n "$response" ]; then
+            echo "$response"
+            return 0
+        fi
+        
+        # If this was the first attempt with auth and it failed, try without auth
+        if [ "$attempt" -eq 1 ] && [ "$use_auth" = true ]; then
+            print_warning "API call with GH_TOKEN failed. Retrying without authentication..." >&2
+            print_warning "Your GH_TOKEN may be incompatible (typically SSO) with this request." >&2
+            use_auth=false
+            # Don't count this as a retry attempt, just switch auth mode
+            continue
+        fi
+        
+        # If we haven't exhausted retries, wait and try again
+        if [ "$attempt" -lt "$max_retries" ]; then
+            print_warning "Fetch attempt $attempt failed (exit code: $exit_code). Retrying in ${retry_delay}s..." >&2
+            sleep $retry_delay
+            retry_delay=$((retry_delay * 2))
+        else
+            print_error "Failed to fetch release data after $max_retries attempts" >&2
+        fi
+    done
 
-    echo "$response"
-    return 0
+    return 1
 }
 
 # Get version (use provided version or fetch latest)
 VERSION=${1:-""}
 REPO="githubnext/gh-aw"
 
 if [ -z "$VERSION" ]; then
-    print_info "Fetching latest release information..."
+    print_info "No version specified, fetching latest release information from GitHub..."
 
     if ! LATEST_RELEASE=$(fetch_release_data "https://api.github.com/repos/$REPO/releases/latest"); then
-        print_error "Failed to fetch latest release information"
+        print_error "Failed to fetch latest release information from GitHub API"
+        print_info "You can specify a version directly: ./install-gh-aw.sh v1.0.0"
         exit 1
     fi
 
@@ -206,7 +231,7 @@ for attempt in $(seq 1 $MAX_RETRIES); do
         print_success "Binary downloaded successfully"
         break
     else
-        if [ $attempt -eq $MAX_RETRIES ]; then
+        if [ "$attempt" -eq "$MAX_RETRIES" ]; then
             print_error "Failed to download binary from $DOWNLOAD_URL after $MAX_RETRIES attempts"
             print_info "Please check if the version and platform combination exists in the releases."
             exit 1

install-gh-aw.sh

@@ -112,6 +112,9 @@ var sanitizeWorkflowNameScript string
 //go:embed js/load_agent_output.cjs
 var loadAgentOutputScript string
 
+//go:embed js/lock-issue.cjs
+var lockIssueScript string
+
 //go:embed js/staged_preview.cjs
 var stagedPreviewScript string
 
@@ -278,6 +281,7 @@ func GetJavaScriptSources() map[string]string {
 		"sanitize_label_content.cjs":        sanitizeLabelContentScript,
 		"sanitize_workflow_name.cjs":        sanitizeWorkflowNameScript,
 		"load_agent_output.cjs":             loadAgentOutputScript,
+		"lock-issue.cjs":                    lockIssueScript,
 		"staged_preview.cjs":                stagedPreviewScript,
 		"assign_agent_helpers.cjs":          assignAgentHelpersScript,
 		"safe_output_helpers.cjs":           safeOutputHelpersScript,

pkg/workflow/js.go

@@ -0,0 +1,40 @@
+// @ts-check
+/// <reference types="@actions/github-script" />
+
+/**
+ * Lock a GitHub issue without providing a reason
+ * This script is used in the activation job when lock-for-agent is enabled
+ * to prevent concurrent modifications during agent workflow execution
+ */
+
+async function main() {
+  // Get issue number from context
+  const issueNumber = context.issue.number;
+
+  if (!issueNumber) {
+    core.setFailed("Issue number not found in context");
+    return;
+  }
+
+  const owner = context.repo.owner;
+  const repo = context.repo.repo;
+
+  core.info(`Locking issue #${issueNumber} for agent workflow execution`);
+
+  try {
+    // Lock the issue without providing a lock_reason parameter
+    await github.rest.issues.lock({
+      owner,
+      repo,
+      issue_number: issueNumber,
+    });
+
+    core.info(`✅ Successfully locked issue #${issueNumber}`);
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    core.error(`Failed to lock issue: ${errorMessage}`);
+    core.setFailed(`Failed to lock issue #${issueNumber}: ${errorMessage}`);
+  }
+}
+
+await main();

pkg/workflow/js/lock-issue.cjs

@@ -232,6 +232,38 @@ else
     exit 1
 fi
 
+# Verify the function has retry logic with max_retries
+if grep -q 'local max_retries=3' "$PROJECT_ROOT/install-gh-aw.sh"; then
+    echo "  ✓ PASS: Function has max_retries=3 variable"
+else
+    echo "  ✗ FAIL: Function does not have max_retries variable"
+    exit 1
+fi
+
+# Verify the function has retry loop
+if grep -q 'for attempt in $(seq 1 $max_retries)' "$PROJECT_ROOT/install-gh-aw.sh"; then
+    echo "  ✓ PASS: Function has retry loop"
+else
+    echo "  ✗ FAIL: Function does not have retry loop"
+    exit 1
+fi
+
+# Verify the function logs fetch attempts
+if grep -q 'Fetching release data (attempt' "$PROJECT_ROOT/install-gh-aw.sh"; then
+    echo "  ✓ PASS: Function logs fetch attempts"
+else
+    echo "  ✗ FAIL: Function does not log fetch attempts"
+    exit 1
+fi
+
+# Verify the function has exponential backoff for retries
+if grep -q 'retry_delay=\$((retry_delay \* 2))' "$PROJECT_ROOT/install-gh-aw.sh"; then
+    echo "  ✓ PASS: Function has exponential backoff for retries"
+else
+    echo "  ✗ FAIL: Function does not have exponential backoff"
+    exit 1
+fi
+
 # Test 9: Verify retry logic for downloads
 echo ""
 echo "Test 9: Verify download retry logic"