Connect a repository

Two things have to be true before commits turn into entries: the provider must deliver pushes to Clocktopus, and the repository must be attached to a project. Miss the second and the deliveries arrive with nowhere to go.

Pull request events feed the delivery metrics — how long reviews take, what is open, what has gone stale. None of that can be recovered from pushes: opening a pull request pushes nothing at all, and a merge names it only in the commit message, or not even there after a rebase merge.

Method	Use it for	What you do
GitHub App	GitHub. Recommended.	Install once. Clocktopus adds the webhook for you, subscribed to all three events.
Manual webhook	Bitbucket, or GitHub without installing an app	Paste a URL and a secret into the provider's settings.

The App is recommended for GitHub because the manual path has one quiet failure: Pushes alone is enough for time tracking, so a webhook with only that box ticked looks like it works while every delivery metric stays empty. The App ticks all three. A manual GitHub webhook is checked the moment you save it: Clocktopus names any event it leaves unticked.

GitHub App

Go to Settings → Git connection and choose Install on GitHub. GitHub asks which account or organisation to install on and which repositories the app may see. Save, and GitHub sends you back here.

The app has no access to your source code. What it asks for is permission to manage webhooks, and that is how it connects: it adds the same webhook you would otherwise add by hand, to the same three events, signed with a secret only it and Clocktopus know.

What it adds depends on where you installed it, because GitHub has no account-level webhook:

Installed on	What Clocktopus adds
An organisation	One webhook on the organisation, covering every repository it owns
A personal account	One webhook per repository, added when you attach that repository to a project

An organisation webhook receives pushes from every repository the organisation owns, including ones you did not select for the app. Commits from a repository not linked to a project are still recorded, with no project and no alert, and that is worth knowing before you install. They turn into time only for a member of your Clocktopus organisation who is known to have written them, and then only as that person's own unassigned time — never yours for having installed the app.

Every installation is connected for one of your Clocktopus organisations — the only one you have, or the one you pick next to Install on GitHub. You can move it to another of your organisations later from its menu. Deliveries book against that organisation's projects, and every member of it is credited for their own commits, so one installation is enough for a team. Someone with a Clocktopus account who is not a member is suggested as an invite instead.

Once installed, the installation shows as Connected on the Git connection page, and Webhooks beneath it lists what is on GitHub right now — one somebody deleted, switched off or edited there says so, with Repair to put it back. One on a repository you have since deselected shows No access instead, because Repair cannot reach it — give the app that repository again under Change repositories on GitHub, which is also where you change what it can see. Disconnect removes the webhooks it added and uninstalls the app.

GitHub allows the app once per account, so installing it again from another Clocktopus account hands back the same installation. If that installation already delivers into an organisation you do not administer, Clocktopus refuses rather than move it, and names the organisation — ask one of its owners or admins to disconnect it first. Owners and admins see every installation their organisation receives on this page, whoever connected it.

Connect with a webhook

You give the repository a URL and a secret, and it posts events to Clocktopus. The same method covers GitHub and Bitbucket, and Clocktopus never holds a credential on your repository — nothing it receives is anything the repository did not send.

One thing to watch as you go: Pushes alone is enough for time tracking, so a webhook with only that box ticked looks like it works while every delivery metric stays empty. Tick the pull request events too — the provider sections below name the exact boxes. On GitHub you find out straight away if you missed one; Bitbucket says nothing until the first push.

Get your webhook URL

The URL is unique to you. It is also on Settings → Git connection, under Webhook URL. Which organisation a webhook delivers for comes from its secret, below — so one URL serves every organisation you belong to.

Create a secret

Every delivery is signed, and Clocktopus rejects anything that fails the check — GitHub signs with SHA-256, Bitbucket with an HMAC. Create a secret here and paste the same value into the provider. A secret is created for an organisation: if you belong to more than one, pick it as you create the secret. Only a repository admin can add a webhook, so the admin who sets one up is tracking the team — every member of that organisation is credited for their own commits.

The secret is shown once. If you lose it, create another and update the provider.

GitHub

Go to Settings → Webhooks → Add webhook, on either the repository or the organisation.

Field	Value
Payload URL	Your webhook URL from above
Content type	application/json
Secret	The secret you just created
Events	Let me select individual events → Pushes, Pull requests, Pull request reviews
Active	Checked

Save with Add webhook. GitHub immediately sends a ping, which carries the webhook's settings. Clocktopus checks its signature like any other delivery and records which events the webhook sends, so within seconds Settings → Git connection shows, under the secret, where the webhook was added and any of the three events it is missing — for example Seen on acme-co/acme-portal, missing: Pull request reviews. A ping signed with a different secret shows up as a Signature mismatch under delivery failures instead. Either way, fix it in the webhook's settings on GitHub and choose Redeliver on the ping under Recent Deliveries to check again.

Which event powers what

Pushes alone is enough for time tracking, and is what an existing webhook is probably set to — GitHub subscribes to it by default. The other two are what fill the delivery metrics, and they are not interchangeable:

Event	What it makes possible
Pushes	Time entries, commit counts, and the effort behind every other figure
Pull requests	Open / stale / merged / abandoned, cycle time, merge rate, work complexity
Pull request reviews	Review rate, time to first review, and review cycles — nothing else does

Leave Pull request reviews off and everything else still works, but review timing disappears entirely and the review rate undercounts: without it the only review Clocktopus can still see is a pull request merged by somebody other than its author.

application/x-www-form-urlencoded also works, so an existing webhook set that way keeps running. GitHub's own webhook documentation covers the screen in more detail.

Bitbucket

Go to Workspace settings → Webhooks → Add webhook. A workspace webhook covers every repository in the workspace, so a project with several repositories needs only one. Repository settings → Webhooks works too, but then every repository needs its own.

Under Triggers, choose Choose from a full list of triggers and tick these eight:

Section	Triggers
Repository	Push
Pull request	Created, Updated, Merged, Declined, and for review tracking Approved, Changes Request created, Comment created

Set the URL to your webhook URL from above, the secret to the one you just created, and leave Active ticked.

Approved, Changes Request created and Comment created are Bitbucket's review triggers, the equivalent of GitHub's Pull request reviews. Without them the review rate and review cycles stay empty. Clocktopus ignores every other trigger, including the other comment triggers (Comment updated, Deleted, Resolved, Reopened) and Approval removed, so leave them unticked.

Bitbucket sends no diff statistics on pull request events, so pull request size stays blank for Bitbucket repositories. Everything else — timings, states, review turnaround — works the same as GitHub.

Save with Save or Create webhook. Atlassian's webhook documentation covers the screen in more detail.

Attach the repository to a project

Open the project in Settings → Projects and use its Repository URLs card — Add from GitHub picks from the repositories your installation can see, or paste any repository URL by hand. GitHub and Bitbucket URLs both go in the same place.

This is also the step that turns delivery on for a personal GitHub App installation: the webhook is added to a repository when you attach it, and removed when you detach it or archive the project.

Commits from a repository that is not listed on a project are kept, and your own show up as unassigned time that only you can see. No project, report or budget counts them until the repository is attached. Attaching it is also what gives agent spend somewhere to land — an agent running in an unattached repository is recorded, but lands in the unattributed row rather than against a client.

Where a repository's time goes

Attribution follows one fact: is the repository attached to a project? Dates play no part.

• Attaching a repository moves its unassigned time into the project, once, whatever day it was logged — locked days included, because unassigned time was never on an invoice. Add to a project shows how much will move before you confirm. Cost still comes from the rates in effect on each day.
• After that, every push, pull request and agent session from the repository lands on the project.
• Detaching, archiving or editing the project never moves time that is already on it. New pushes from a repository no live project links go back to unassigned and show up on To sort.
• Moving a repository to another project leaves its history where it is; new work follows the new project. Time booked to the wrong project is fixed by editing those entries.

Time you log by hand is not affected: it goes on whichever project you pick.

Within an organisation a repository is attached to one live project at a time — remove it from the first before attaching it to a second. That is checked when you attach it.

A repository two of your organisations attach

If you work for an agency and its client and both attach the same repository, your work from it goes to the project that attached it first. To send it to the other side, open one of its entries on the Time page and use Choose organisation: that entry and your new work from the repository follow your choice, and the button goes away. Locked days keep their project.

Repositories waiting for a project

To sort → Repositories lists every repository with unassigned time that no project links: its commits, first and last activity, unassigned hours and your unattributed agent sessions on it. A member sees the repositories behind their own work; an owner or admin sees every repository the organisation's streams deliver. From each row you can:

• Create project — opens a new project with the repository filled in and a name taken from it. Its unassigned time moves into the new project.
• Add to a project — pick a project you manage. You see how much unassigned time will move into it before you confirm.
• Ignore — for side projects and dotfiles. The repository leaves the list, and the webhooks and installations you connected stop making you time from it from now on. Its commits are still kept, and other people are unaffected. Linking the repository to one of your projects later overrides the ignore. Stop ignoring brings it back, but does not create time for the pushes it skipped.

A delivery only ever books to its organisation's projects

A delivery belongs to the organisation its webhook secret or installation was connected for, and that decides where the time lands. It resolves the repository against that organisation's projects, and only then works out which members to credit — so a push can never create entries in an organisation that did not connect it, whoever wrote the commits.

Two unrelated organisations can therefore track the same repository without interfering: each adds its own webhook and maps the repository in its own project. A repository accepts many webhooks, so nothing has to be shared, and a commit delivered by both is only ever booked once.

Within one team the opposite is true, and deliberately: one connection is enough. Every member who can access the project is credited for their own commits from the same delivery.

Make sure your commits are yours

Git stamps commits with the email in your local config, not the one you sign in with:

git config user.email

If it differs from your Clocktopus login, add and confirm it under commit addresses. The address also has to belong to someone who can access the project the repository is attached to — a commit written by an outside address is listed under To sort → Commit authors rather than credited to a stranger.

Check it worked

Push something, then look at Settings → Git connection for recent deliveries. Two failures account for nearly all of them:

• Invalid signature — the secret in the provider does not match the one in Clocktopus, or the repository URL on the project does not match the repository actually sending. A webhook the App installed cannot fail this check: nobody typed the secret.
• Delivered, but no entry — the commit author email is not tracked. (A repository not attached to a project still creates entries, unassigned.)