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

# Git Sync Automation

> Automate workflows between Git providers and Agile Tools

# Git Sync Automation

Once an Administrator has connected your Git provider (GitHub, GitLab, or Bitbucket), you can automate workflows and customize how data syncs between systems.

> [!NOTE]
>
> **Prerequisite:** This guide requires an active SCM connection established by
> an Administrator. If your organization hasn't connected a Git provider yet,
> see: - [GitHub Integration Setup](https://docs.agile-tools.io/en/admin/integrations/github.md) - [GitLab
> Integration Setup](https://docs.agile-tools.io/en/admin/integrations/gitlab.md) - [Bitbucket Integration
> Setup](https://docs.agile-tools.io/en/admin/integrations/bitbucket.md)

## Commit Linking

Reference Agile Tools items in your commit messages:

```bash theme={null}
# Link to a Value Item
git commit -m "Implement feature [AT-123]"

# Link multiple items
git commit -m "Fix bugs [AT-456] [AT-789]"

# Link to a Key Result
git commit -m "Add metrics tracking [KR-42]"
```

### Supported Reference Formats

| Format | Links to | Example |
| - | - | - |
| `[AT-123]` | Value Item | `[AT-123]` |
| `[KR-123]` | Key Result | `[KR-42]` |
| `[OKR-123]` | Objective | `[OKR-7]` |

## Webhooks

Agile Tools receives webhook events from your Git provider. Use the API to query commit activity:

```bash theme={null}
curl -H "Authorization: Bearer $TOKEN" \
  "https://api.agile-tools.io/v1/value-items/AT-123/commits"
```

Response:

```json theme={null}
{
  "data": [
    {
      "sha": "abc123def456",
      "message": "Implement feature [AT-123]",
      "author": "developer@example.com",
      "timestamp": "2025-12-20T14:30:00Z",
      "repository": "acme/web-app"
    }
  ]
}
```

## Field Mapping

Customize how Git events update Agile Tools fields. See [Field Mapping](https://docs.agile-tools.io/en/developer/integrations/field-mapping.md) for:

* Mapping branch names to Value Item states
* Automatic progress updates from merged PRs
* Custom metadata extraction from commits

## Automation Examples

### Update Key Result on Merge

When a PR is merged, update a Key Result's progress:

```javascript theme={null}
// Webhook handler example
app.post("/webhooks/github", (req, res) => {
  const { action, pull_request } = req.body;

  if (action === "closed" && pull_request.merged) {
    const krMatch = pull_request.title.match(/\[KR-(\d+)\]/);
    if (krMatch) {
      // Call Agile Tools API to update progress
      updateKeyResultProgress(krMatch[1], pull_request);
    }
  }

  res.sendStatus(200);
});
```

### Sync Repository as Value Unit

Import a repository as a Value Unit via API:

```bash theme={null}
curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "product",
    "name": "Web Application",
    "externalId": "github:acme/web-app",
    "syncEnabled": true
  }' \
  "https://api.agile-tools.io/v1/value-units"
```

## API Endpoints for Git Integration

| Endpoint | Method | Description |
| - | - | - |
| `/integrations/scm/status` | GET | Check connection status |
| `/integrations/scm/repositories` | GET | List connected repositories |
| `/value-items/{id}/commits` | GET | Get commits linked to an item |
| `/key-results/{id}/commits` | GET | Get commits linked to a KR |

## Related

* [Webhooks Guide](https://docs.agile-tools.io/en/developer/api/webhooks.md) — General webhook setup
* [Field Mapping](https://docs.agile-tools.io/en/developer/integrations/field-mapping.md) — Customize sync behavior
* [API Authentication](https://docs.agile-tools.io/en/developer/api/authentication.md) — Get your API token


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.