Lesson 2 · Adding and synchronising a repository

Linking it to a product and project, syncing, the webhook; old history and quiet linking.

Goal of this lessonTo link a repository to a product and a project, synchronise it and install the webhook for live updates.

How data flows from GitHub to PORTWAREGitHubrepositoryWebhookinstant, signedSynchronisationevery 30 minutesPORTWARErecordsTaskProductMatrix
The webhook brings a change at once; the synchronisation is the safety net when no webhook is installed or a delivery was missed. Unchanged data costs nothing from GitHub's request budget.

Step by step

  1. Add the repository

    In Project › GitHub › Repositories press New and paste the repository's GitHub URL (https://github.com/owner/repo or owner/repo). Find Repositories on the connection also creates them, archived; you activate the ones you use.

  2. Link it to a product and a project, then sync

    On the repository form fill Products and Projects and press Sync Now. The first sync reads the last 90 days; the overview shows the README, open work, the latest release and the delivery figures.

    The repository form123456
    1. Sync Now: reads the repository now; it also runs by itself every 30 minutes.
    2. Counters: open PRs, commits, open issues, releases and SBOM; a click opens the list.
    3. Products: the products that ship the software.
    4. Projects: the projects that build it; task links are made within them.
    5. Link keys from: keys in messages older than the connection are not read.
    6. Overview: open PRs, open issues, latest release, days to merge and stars.

  3. Install the webhook

    Install Webhook adds the webhook to the repository on GitHub (the token needs Webhooks write). From then on pushes, pull requests, releases and builds arrive at once; deliveries are listed in GitHub › Webhook Deliveries.

Old history is not read for keys
A repository with years of history may hold words like "T17" in old messages; they are not PORTWARE tasks. Keys are therefore read only from work written after the connection. Link an older change to a task by hand or with Cowork.
History arrives quietly
The first sync, or a permission added later, brings history but moves no task, posts no note and runs no old command. Automation acts on new events only.

Check yourself

Does data arrive without the webhook?
Yes, through the 30-minute sync; the webhook only makes it instant.
How is a commit from before the connection tied to a task?
By hand (Tasks on the commit form) or by asking Cowork to link it to T163.