Delivery

Delivery configuration controls how AgentGate ships completed work. This includes Git operations, pull request creation, and notifications to stakeholders.

What Is Delivery

After an agent successfully completes a task (all gates pass), the delivery phase:

Commits changes to Git with structured messages
Creates branches following naming conventions
Opens pull requests with metadata and reviewers
Sends notifications via Slack, email, or webhooks

Delivery Specification

spec:
  delivery:
    git:
      mode: github-pr
      branchPrefix: "fix/"
      commitPrefix: "[AgentGate]"
      autoCommit: true
      autoPush: true

    pr:
      create: true
      draft: false
      title: "fix: {task}"
      labels:
        - agent-generated
        - needs-review
      reviewers:
        - senior-dev

    notifications:
      onSuccess:
        - type: slack
          webhook: "https://hooks.slack.com/..."
          channel: "#deployments"

Git Modes

AgentGate supports three Git operation modes:

Local
Push
GitHub PR

Commit locally onlyChanges are committed but not pushed. Use for local development or when you want manual control over pushing.

delivery:
  git:
    mode: local
    autoCommit: true

Workflow:

Agent completes work
Changes committed to local branch
No remote operations

Best for:

Local development
Manual review before push
Testing and debugging

Commit and push to remoteChanges are committed and pushed to the remote branch.

delivery:
  git:
    mode: push
    branchPrefix: "feature/"
    autoCommit: true
    autoPush: true

Workflow:

Agent completes work
Changes committed to new branch
Branch pushed to remote

Best for:

Direct pushes to feature branches
CI/CD pipelines without PRs
Automated workflows

Create a pull requestThe full GitHub workflow: commit, push, and create a PR.

delivery:
  git:
    mode: github-pr
    branchPrefix: "fix/"
    autoCommit: true
    autoPush: true

  pr:
    create: true
    title: "fix: {task}"
    reviewers:
      - team-lead

Workflow:

Agent completes work
Changes committed to new branch
Branch pushed to remote
Pull request created with metadata

Best for:

Team collaboration
Code review workflows
Production deployments

Git Configuration

Git Spec Options

git:
  mode: github-pr            # local | push | github-pr
  branchPrefix: "fix/"       # Prefix for branch names
  branchName: "custom-name"  # Override full branch name
  commitPrefix: "[Bot]"      # Prefix for commit messages
  commitTemplate: |          # Custom commit template
    {type}: {task}

    Changes:
    {changes}

    Generated by AgentGate
  autoCommit: true           # Auto-commit changes
  autoPush: true             # Auto-push to remote
  signCommits: false         # GPG sign commits

Configuration Options

Option	Type	Default	Description
`mode`	string	`local`	Git operation mode
`branchPrefix`	string	`agentgate/`	Prefix for new branch names
`branchName`	string	-	Override entire branch name
`commitPrefix`	string	`[AgentGate]`	Prefix for commit messages
`commitTemplate`	string	-	Custom commit message template
`autoCommit`	boolean	`true`	Automatically commit changes
`autoPush`	boolean	`false`	Automatically push to remote
`signCommits`	boolean	`false`	Sign commits with GPG

Branch Naming

Branches are named using the pattern: {branchPrefix}{task-slug}

# With branchPrefix: "fix/"
# Task: "Fix null pointer in auth"
# Branch: fix/fix-null-pointer-in-auth

# Override with branchName
branchName: "hotfix/auth-npe-fix"
# Branch: hotfix/auth-npe-fix

Commit Messages

Commit messages can be customized using templates:

commitTemplate: |
  {type}: {task}

  {changes}

  Work Order: {workOrderId}
  Run: {runId}
  Generated by AgentGate

Available Variables:

Variable	Description
`{type}`	Commit type (fix, feat, etc.)
`{task}`	Task description
`{changes}`	List of changed files
`{workOrderId}`	Work order ID
`{runId}`	Run ID
`{date}`	Current date

Pull Request Configuration

Configure pull request creation for the github-pr mode:

pr:
  create: true
  draft: false
  title: "feat(auth): {task}"
  body: |
    ## Summary
    {task}

    ## Changes
    {changes}

    ## Testing
    - [ ] Unit tests pass
    - [ ] Integration tests pass

    ---
    Generated by AgentGate
  labels:
    - feature
    - agent-generated
    - needs-review
  reviewers:
    - lead-dev
    - security-team
  assignees:
    - platform-team
  base: main
  autoMerge:
    enabled: false
    method: squash
    waitForChecks: true
    deleteOnMerge: true

PR Spec Options

Option	Type	Default	Description
`create`	boolean	`true`	Whether to create a PR
`draft`	boolean	`false`	Create as draft PR
`title`	string	-	PR title (supports templates)
`body`	string	-	PR body (supports templates)
`labels`	string[]	-	Labels to add to PR
`reviewers`	string[]	-	GitHub usernames for review
`assignees`	string[]	-	GitHub usernames to assign
`base`	string	default branch	Base branch for PR
`autoMerge`	object	-	Auto-merge configuration

Auto-Merge Configuration

Enable automatic merging after checks pass:

autoMerge:
  enabled: true
  method: squash       # merge | squash | rebase
  waitForChecks: true  # Wait for CI checks
  deleteOnMerge: true  # Delete branch after merge

Auto-merge requires the repository to have branch protection rules enabled and the allow auto-merge setting turned on.

Notifications

Send notifications when tasks complete or fail:

notifications:
  onSuccess:
    - type: slack
      webhook: "https://hooks.slack.com/services/..."
      channel: "#deployments"
      template: "Task completed: {task}"

    - type: email
      to:
        - team@company.com
      subject: "AgentGate: {task} completed"

  onFailure:
    - type: slack
      webhook: "https://hooks.slack.com/services/..."
      channel: "#alerts"
      template: "Task failed: {task}. Error: {error}"

    - type: webhook
      url: "https://api.pagerduty.com/incidents"
      method: POST
      headers:
        Authorization: "Token token=${PAGERDUTY_TOKEN}"

Notification Types

Slack
Email
Webhook

Send to Slack channel

notifications:
  onSuccess:
    - type: slack
      webhook: "https://hooks.slack.com/services/T00/B00/XXX"
      channel: "#deployments"
      template: |
        :white_check_mark: *Task Completed*
        Task: {task}
        PR: {prUrl}
        Duration: {duration}

Options:

Option	Type	Description
`webhook`	string	Slack webhook URL
`channel`	string	Channel override
`template`	string	Message template

Send email notification

notifications:
  onFailure:
    - type: email
      to:
        - team@company.com
        - oncall@company.com
      subject: "AgentGate Task Failed: {task}"
      template: |
        Task: {task}
        Work Order: {workOrderId}
        Error: {error}

        Please investigate.

Options:

Option	Type	Description
`to`	string[]	Email recipients
`subject`	string	Email subject template
`template`	string	Email body template

Call custom HTTP endpoint

notifications:
  onSuccess:
    - type: webhook
      url: "https://api.example.com/hooks/agentgate"
      method: POST
      headers:
        Authorization: "Bearer ${API_TOKEN}"
        Content-Type: "application/json"

Options:

Option	Type	Description
`url`	string	Webhook URL
`method`	string	HTTP method (POST, PUT)
`headers`	object	Custom headers

Payload sent:

{
  "event": "success",
  "workOrderId": "wo_123",
  "runId": "run_456",
  "task": "Fix auth bug",
  "prUrl": "https://github.com/org/repo/pull/789",
  "duration": 3600000,
  "timestamp": "2024-01-15T10:30:00Z"
}

Template Variables

Available in notification templates:

Variable	Description
`{task}`	Task description
`{workOrderId}`	Work order ID
`{runId}`	Run ID
`{prUrl}`	Pull request URL
`{prNumber}`	Pull request number
`{branch}`	Branch name
`{commit}`	Commit SHA
`{duration}`	Execution duration
`{error}`	Error message (failures only)
`{iterations}`	Number of iterations

Complete Examples

Minimal Delivery

delivery:
  git:
    mode: local

Standard PR Workflow

delivery:
  git:
    mode: github-pr
    branchPrefix: "feat/"
    commitPrefix: "[Feature]"
    autoCommit: true
    autoPush: true

  pr:
    create: true
    draft: false
    title: "feat: {task}"
    labels:
      - enhancement
      - agent-generated
    reviewers:
      - team-lead

Full-Featured Delivery

delivery:
  git:
    mode: github-pr
    branchPrefix: "fix/"
    commitPrefix: "[Hotfix]"
    commitTemplate: |
      fix: {task}

      This change addresses a critical bug in the system.

      Changes:
      {changes}

      Work Order: {workOrderId}
      Generated by AgentGate
    autoCommit: true
    autoPush: true
    signCommits: false

  pr:
    create: true
    draft: false
    title: "fix: {task}"
    body: |
      ## Summary
      Automated fix for: {task}

      ## Changes Made
      {changes}

      ## Verification
      - All gates passed
      - {iterations} iteration(s) to complete

      ## Testing
      - [ ] Review automated changes
      - [ ] Run manual smoke tests
      - [ ] Verify in staging

      ---
      Generated by AgentGate | Work Order: {workOrderId}
    labels:
      - bug
      - hotfix
      - agent-generated
      - needs-review
    reviewers:
      - senior-dev
      - security-team
    assignees:
      - on-call-team
    base: main
    autoMerge:
      enabled: true
      method: squash
      waitForChecks: true
      deleteOnMerge: true

  notifications:
    onSuccess:
      - type: slack
        webhook: "https://hooks.slack.com/services/T00/B00/XXX"
        channel: "#deployments"
        template: |
          :white_check_mark: *Hotfix Deployed*
          Task: {task}
          PR: {prUrl}
          Branch: `{branch}`
          Duration: {duration}

      - type: email
        to:
          - engineering@company.com
        subject: "Hotfix Completed: {task}"
        template: |
          A hotfix has been automatically applied and is pending review.

          Task: {task}
          Pull Request: {prUrl}
          Work Order: {workOrderId}

          Please review at your earliest convenience.

    onFailure:
      - type: slack
        webhook: "https://hooks.slack.com/services/T00/B00/XXX"
        channel: "#alerts"
        template: |
          :x: *Hotfix Failed*
          Task: {task}
          Error: {error}
          Work Order: {workOrderId}

      - type: webhook
        url: "https://api.pagerduty.com/incidents"
        method: POST
        headers:
          Authorization: "Token token=${PAGERDUTY_TOKEN}"

Delivery Results

After delivery, AgentGate returns structured results:

interface DeliveryResult {
  success: boolean;
  mode: 'local' | 'push' | 'github-pr';
  commit?: {
    success: boolean;
    sha?: string;
    filesCommitted: string[];
    error?: string;
  };
  push?: {
    success: boolean;
    remote?: string;
    branch?: string;
    error?: string;
  };
  pr?: {
    success: boolean;
    prNumber?: number;
    url?: string;
    error?: string;
  };
  notifications?: {
    type: string;
    success: boolean;
    error?: string;
  }[];
  error?: string;
}

Best Practices

Use Descriptive Branch Names

Use branch prefixes that indicate the type of change:

fix/ for bug fixes
feat/ for features
refactor/ for refactoring
docs/ for documentation

Add Meaningful Labels

Labels help with organization and filtering:

labels:
  - agent-generated  # Always identify agent work
  - needs-review     # Require human review
  - priority/high    # Categorize urgency

Assign Appropriate Reviewers

Match reviewers to the type of change:

reviewers:
  - security-team    # For auth changes
  - database-team    # For schema changes
  - frontend-team    # For UI changes

Configure Failure Notifications

Always set up failure notifications for visibility:

notifications:
  onFailure:
    - type: slack
      channel: "#alerts"

Use Auto-Merge Carefully

Only enable auto-merge for well-tested, low-risk changes:

autoMerge:
  enabled: true
  waitForChecks: true  # Always wait for CI

Troubleshooting

Push fails with authentication error

Ensure GitHub token has push permissions:

# Check token scopes
gh auth status

# Verify push access
git push --dry-run

PR creation fails

Check repository permissions:

Token needs repo scope for private repos
Token needs public_repo for public repos

# Test PR creation
gh pr create --title "Test" --body "Test" --dry-run

Slack notification fails

Verify webhook URL is correct:

curl -X POST -H 'Content-type: application/json' \
  --data '{"text":"Test message"}' \
  "https://hooks.slack.com/services/T00/B00/XXX"

Auto-merge not working

Check repository settings:

Branch protection rules must be enabled
“Allow auto-merge” must be checked in repo settings
All required checks must be passing

TaskSpec

Configure delivery within TaskSpec

Execution

Execution environment configuration

Gates

Verification before delivery

GitHub Integration

Set up GitHub integration

​Delivery

​What Is Delivery

​Delivery Specification

​Git Modes

​Git Configuration

​Git Spec Options

​Configuration Options

​Branch Naming

​Commit Messages

​Pull Request Configuration

​PR Spec Options

​Auto-Merge Configuration

​Notifications

​Notification Types

​Template Variables

​Complete Examples

​Minimal Delivery

​Standard PR Workflow

​Full-Featured Delivery

​Delivery Results

​Best Practices

​Troubleshooting

​Related

TaskSpec

Execution

Gates

GitHub Integration

Delivery

What Is Delivery

Delivery Specification

Git Modes

Git Configuration

Git Spec Options

Configuration Options

Branch Naming

Commit Messages

Pull Request Configuration

PR Spec Options

Auto-Merge Configuration

Notifications

Notification Types

Template Variables

Complete Examples

Minimal Delivery

Standard PR Workflow

Full-Featured Delivery

Delivery Results

Best Practices

Troubleshooting

Related