# Git sync

> Connect GitHub, GitLab or Bitbucket so commits, branches and pull requests link to tasks automatically.

> For the complete documentation index, see [llms.txt](https://helpdesk.orangescrum.com/llms.txt).

Source: https://helpdesk.orangescrum.com/guide/cloud/integrations/git-sync

---
> **Pro and Premium**
>
> GitHub, GitLab and Bitbucket sync require Pro Unlimited or above.

Git sync links code to the task it belongs to. Reference a task key in a commit
message or branch name and the commit appears on that task — no manual copying,
and a permanent record of which change addressed which requirement.

## Connecting

**Open project settings → Integrations**

    Git sync is configured **per project**, so each project links to the right
    repository.

**Authorise the provider**

    GitHub, GitLab or Bitbucket. You will be asked to grant access.

> **Tip**
>
> Use a service account rather than a personal one. A connection wired to an
> individual breaks the day they leave.

**Pick the repository**

    One project can watch more than one repo where that reflects reality.

**Test it**

    Push a commit referencing a task key and confirm it appears on the task.

## Referencing tasks

Include the task key — the project short name plus the number — in the commit
message or branch name:

```bash
git commit -m "WR-142 fix checkout redirect on mobile Safari"

git checkout -b WR-142-checkout-redirect
```

> **The short name must match**
>
> The key comes from the project's short name. If the short name is changed
> after people have started referencing it, older commits stop linking. Settle
> the short name early — see
> [Create a project](https://helpdesk.orangescrum.com/guide/cloud/projects/create-a-project).

## What appears on the task

| Event | Shown |
| --- | --- |
| Commit | Message, author, hash, link |
| Branch | Name and status |
| Pull / merge request | Title, state, reviewers |

Which makes a few questions answerable that otherwise are not: what code
implemented this? was it reviewed? has it shipped?

## Habits that make it work

- **Reference in the first line**: Some tooling truncates commit bodies. Put the key at the front.

- **Branch names too**: Then the whole branch links, not just individual commits.

- **One task per branch**: A branch touching five tasks makes the history unreadable.

- **Say what changed**: "WR-142 fix" links correctly and explains nothing. The message is read far more often than it is written.

## Automation

On Pro and above you can automate on Git events — move a task to **In review**
when a pull request opens, or to **Done** when it merges.

> **Merged is not always done**
>
> If your definition of done includes deployment or verification, auto-closing
> on merge marks work complete before it is. Move it to Ready to verify instead.

## Troubleshooting

**Commits aren't appearing**

    In order: is the key formatted correctly (`WR-142`, matching the project
    short name)? Is the connection still authorised — tokens expire silently? Is
    the repo actually the one linked to this project?

**It stopped working after someone left**

    The integration was authorised with their account. Reconnect with a service
    account.

**Wrong task gets linked**

    Two projects with the same or similar short names. Short names need to be
    unique — that is what they are for.

**Too many notifications**

    Every commit is generating a notification. Tune it in project notification
    settings, or people will mute the project entirely.

- [Azure DevOps](https://helpdesk.orangescrum.com/guide/cloud/integrations/azure-devops): Work item sync with Azure Boards.

- [All integrations](https://helpdesk.orangescrum.com/guide/cloud/integrations/overview): What else you can connect.