> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentgate.mynewapi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Delivery

> Understanding delivery - how AgentGate ships completed work via Git, PRs, and notifications

# 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:

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

## Delivery Specification

```yaml theme={null}
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:

<Tabs>
  <Tab title="Local">
    **Commit locally only**

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

    ```yaml theme={null}
    delivery:
      git:
        mode: local
        autoCommit: true
    ```

    **Workflow:**

    1. Agent completes work
    2. Changes committed to local branch
    3. No remote operations

    **Best for:**

    * Local development
    * Manual review before push
    * Testing and debugging
  </Tab>

  <Tab title="Push">
    **Commit and push to remote**

    Changes are committed and pushed to the remote branch.

    ```yaml theme={null}
    delivery:
      git:
        mode: push
        branchPrefix: "feature/"
        autoCommit: true
        autoPush: true
    ```

    **Workflow:**

    1. Agent completes work
    2. Changes committed to new branch
    3. Branch pushed to remote

    **Best for:**

    * Direct pushes to feature branches
    * CI/CD pipelines without PRs
    * Automated workflows
  </Tab>

  <Tab title="GitHub PR">
    **Create a pull request**

    The full GitHub workflow: commit, push, and create a PR.

    ```yaml theme={null}
    delivery:
      git:
        mode: github-pr
        branchPrefix: "fix/"
        autoCommit: true
        autoPush: true

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

    **Workflow:**

    1. Agent completes work
    2. Changes committed to new branch
    3. Branch pushed to remote
    4. Pull request created with metadata

    **Best for:**

    * Team collaboration
    * Code review workflows
    * Production deployments
  </Tab>
</Tabs>

## Git Configuration

### Git Spec Options

```yaml theme={null}
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}`

```yaml theme={null}
# 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:

```yaml theme={null}
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:

```yaml theme={null}
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:

```yaml theme={null}
autoMerge:
  enabled: true
  method: squash       # merge | squash | rebase
  waitForChecks: true  # Wait for CI checks
  deleteOnMerge: true  # Delete branch after merge
```

<Warning>
  Auto-merge requires the repository to have branch protection rules enabled and the `allow auto-merge` setting turned on.
</Warning>

## Notifications

Send notifications when tasks complete or fail:

```yaml theme={null}
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

<Tabs>
  <Tab title="Slack">
    **Send to Slack channel**

    ```yaml theme={null}
    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  |
  </Tab>

  <Tab title="Email">
    **Send email notification**

    ```yaml theme={null}
    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    |
  </Tab>

  <Tab title="Webhook">
    **Call custom HTTP endpoint**

    ```yaml theme={null}
    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:**

    ```json theme={null}
    {
      "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"
    }
    ```
  </Tab>
</Tabs>

### 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

```yaml theme={null}
delivery:
  git:
    mode: local
```

### Standard PR Workflow

```yaml theme={null}
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

```yaml theme={null}
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:

```typescript theme={null}
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

<Steps>
  <Step title="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
  </Step>

  <Step title="Add Meaningful Labels">
    Labels help with organization and filtering:

    ```yaml theme={null}
    labels:
      - agent-generated  # Always identify agent work
      - needs-review     # Require human review
      - priority/high    # Categorize urgency
    ```
  </Step>

  <Step title="Assign Appropriate Reviewers">
    Match reviewers to the type of change:

    ```yaml theme={null}
    reviewers:
      - security-team    # For auth changes
      - database-team    # For schema changes
      - frontend-team    # For UI changes
    ```
  </Step>

  <Step title="Configure Failure Notifications">
    Always set up failure notifications for visibility:

    ```yaml theme={null}
    notifications:
      onFailure:
        - type: slack
          channel: "#alerts"
    ```
  </Step>

  <Step title="Use Auto-Merge Carefully">
    Only enable auto-merge for well-tested, low-risk changes:

    ```yaml theme={null}
    autoMerge:
      enabled: true
      waitForChecks: true  # Always wait for CI
    ```
  </Step>
</Steps>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Push fails with authentication error">
    Ensure GitHub token has push permissions:

    ```bash theme={null}
    # Check token scopes
    gh auth status

    # Verify push access
    git push --dry-run
    ```
  </Accordion>

  <Accordion title="PR creation fails">
    Check repository permissions:

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

    ```bash theme={null}
    # Test PR creation
    gh pr create --title "Test" --body "Test" --dry-run
    ```
  </Accordion>

  <Accordion title="Slack notification fails">
    Verify webhook URL is correct:

    ```bash theme={null}
    curl -X POST -H 'Content-type: application/json' \
      --data '{"text":"Test message"}' \
      "https://hooks.slack.com/services/T00/B00/XXX"
    ```
  </Accordion>

  <Accordion title="Auto-merge not working">
    Check repository settings:

    1. Branch protection rules must be enabled
    2. "Allow auto-merge" must be checked in repo settings
    3. All required checks must be passing
  </Accordion>
</AccordionGroup>

## Related

<CardGroup cols={2}>
  <Card title="TaskSpec" icon="file-code" href="/concepts/task-spec">
    Configure delivery within TaskSpec
  </Card>

  <Card title="Execution" icon="server" href="/concepts/execution">
    Execution environment configuration
  </Card>

  <Card title="Gates" icon="shield-check" href="/concepts/gates">
    Verification before delivery
  </Card>

  <Card title="GitHub Integration" icon="github" href="/guides/github-integration">
    Set up GitHub integration
  </Card>
</CardGroup>