Design

Trigger: git post-receive hook

• Installed into every bare repo under hooks/post-receive at creation time
• One-line addition to RepoHandler.CreateRepo in Sztabina
• Migration script installs hook into all existing repos
• Hook reads stdin (oldSha newSha refName), fetches commit messages via git log, calls POST /internal/notify/push on Sztabina

Sztabina: new internal endpoint

• POST /internal/notify/push
• Receives push data, extracts commits and branch name
• Fires POST /api/internal/hooks/push on Spring backend

Spring backend: IssueReferenceService

• Parses issue keys from commit messages and branch name
• Resolves keys to issue IDs via existing global key lookup
• Persists to issue_references table
• Duplicate guard: upsert on (issue_id, commit_sha, source_type)

PR linking

• On PR create/update: parse PR title for issue keys
• Same IssueReferenceService, source_type = PR

Manual linking

• Issue UI: "Link" button → search/select issue => source_type = MANUAL

New table: issue_references

Visibility

• Issue view: new "References" section showing:
  • Linked commits (sha, message, author, date)
  • Linked PRs (title, status, author)
• PR view: linked issue badge in PR header

Flyway migration

• V16__add_issue_references.sql

Out of scope

• Automatic status transitions on PR merge — separate ticket, policy is complex
• Commit detail page — follow-up

Task breakdown

• post-receive hook script + install on create: 2h
• Sztabina /internal/notify/push endpoint: 3h
• Spring IssueReferenceService + V16 migration: 4h
• PR title parsing on create/update: 2h
• Issue view References section (frontend): 6h
• PR view linked issue badge (frontend): 2h
• Manual link UI: 3h
• Existing repo migration script: 1h
• Testing + regression: 1h

On 19/03/2026 21:23, rk@tigase.net wrote:

I think this will be valuable - I recall you raised this before.

Good memory, I don't remember mentioning it :)

This is my approach to automatic commit <=> issue <=> PR linking using Sztabina push webhooks. Pl let me know if I am overcomplicating:

• On every push, Sztabina fires a webhook to the backend
• Commit messages and branch names are parsed for Sztab issue keys (SZTaa00001 format)
• Matching issues are automatically linked and shown in the issue view
• PR titles are also parsed on creation/update
• Manual linking from the issue UI as a fallback

Thoughts?

Seems about right.

One problem I see is matching the issues from the commit message - over the years we used so many systems that the issue format differed a lot from one to another: from the base #<issue_number> to #<[short-]project-ID>-number to full-blown#-issue-id (e.g. #tigase/_clients/beagle-im#654 or #SZ-122 or #122 )

Sztab will probably have its own ID system so we should think how (if we want past commits association) do that.

Ps: Why not take it a step further with automatic issue status transitions driven by PR state transitions: if a PR title references an issue key and the PR is merged, the issue automatically transitions to RESOLVED. keywords — for example, a commit message containing "fixes SZTsz00121" would automatically move that issue to RESOLVED via the existing state machine. Conversely, when the PR is reopened (APPROVED => IN PROGRESS), the issue goes from R -> O. But this gets complicated as there could be more than one PR addressing an issue - Dobra, nie mieszam, bo się jeszcze zsiądzie.

Some systems do that though, to be honest, I never used that nor was convinced by it. I guess one of the reasons is/was because Tigase is quite modular and quite often you had to make changes in multiple repositories then changes from one could trigger issue state while not finally fixing something. But it could be usefull.

Wojciech,

You asked for issues and pull requests to be linked to each other. Here is what that will look like in Sztab.

Linking happens automatically. Whenever an issue key (e.g. SZTab00001) appears in a commit message, a branch name, or a PR title, Sztab picks it up and creates the link. You do not have to do anything.

From the issue side, a new Linked Items tab will appear in the issue modal, next to Comments and Time. It shows all the branches, commits, and pull requests that mention that issue — as they accumulate over the life of the issue.

From the PR side, any issues associated with that PR appear as small clickable badges near the PR title. Clicking a badge takes you straight to the issue.

If a link was created by mistake — for example because a commit referenced the wrong issue key — it can be removed manually from the issue screen. You can also add links manually if the automatic detection did not pick something up.

Screenshots attached show where these will appear in the UI.

Does this match what you had in mind?

Rk

Items linked to Issues: Screenshot 2026-03-22 at 5.04.49 PM

Items linked to PullRequests: Screenshot 2026-03-22 at 9.33.32 PM

One problem I see is matching the issues from the commit message - over the years we used so many systems that the issue format differed a lot from one to another: from the base #<issue_number> to #<[short-]project-ID>-number to full-blown#-issue-id (e.g. #tigase/_clients/beagle-im#654 or #SZ-122 or #122 )

Past commits in migrated repos will have #654, #SZ-122, #tigase/_clients/beagle-im#654 — none of which match SZT[a-z]{2}\d{5}. For SZ-122 this is explicitly out of scope (forward-looking only), but it should go in the backlog as SZ-122f — a one-time historical commit scan with a pluggable key format adapter.

I hope this is not a deal-breaker.

Artur,

You wanted a release. I would like to include this feature in code drop 1.10.0. I can get this implemented and tested by Tuesday end and release 1.10.0 Wed AM.

I hope this is acceptable.

Hook-based Auto-Linking Design

Flow

1. git push

   • Handled by git-http-backend (CGI)
   • Push is accepted

2. post-receive hook

   • Triggered automatically by Git
   • Reads stdin:

     <old-sha> <new-sha> <ref>
     

   • Invokes:

     sztabina notify --repo <repo> --old <old> --new <new> --ref <ref> &
     

   • Runs asynchronously => does not block push

3. Sztabina (notify mode)

   • Parses CLI args: --repo, --old, --new, --ref
   • Opens repo via LocalGitEngine
   • Calls ListCommitsBetween(old, new)
   • Builds payload:
     • repo name
     • ref (branch)
     • commit list (sha, message, metadata)
   • POSTs to:

     /internal/hooks/receive
     

   • Retry with timeout (--connect-timeout 3, --max-time 5)

4. Spring Boot

   • HookReceiveController
     • Validates shared secret
     • Calls IssueLinkService.processHook(...)

5. IssueLinkService

   • Resolve project via projectRepository.findByName(repoName)
   • Extract issue keys from:
     • branch name (ref)
     • commit messages
   • Upsert into:
     • issue_commit_links
     • issue_branch_links

6. Existing repos

   • sztabina install-hooks
   • Walks GIT_REPO_ROOT
   • Installs post-receive hook in each repo

Flow of data across three domains: git client, Sztabina and Sztab:

User triggers a git push using git client, which causes Sztabina to trigger the hook, which in turn enriches the content and calls IssueLinkService to link the commit to the issue.

Screenshot 2026-03-23 at 4.18.38 PM

PR: https://tigase.dev/sztab/~pulls/20

Wojciech,

Btw. you can user-mention with @ in issues -- you don't have to send explicit emails :)

Does this match what you had in mind?

From the screenshots it seems to look OK.

Though I'm not sure about the actual issue IDs. (SZT[a-z]{2}\d{5}) is mentioned in the PR (and below) and as example SZTab00001 -- could you elaborate on issue IDs? Are they actually upper-lower-case mixed and the lower-case serves as a separator somehow?

Past commits in migrated repos will have #654, #SZ-122, #tigase/_clients/beagle-im#654 — none of which match SZT[a-z]{2}\d{5}. For SZ-122 this is explicitly out of scope (forward-looking only), but it should go in the backlog as SZ-122f — a one-time historical commit scan with a pluggable key format adapter.

I hope this is not a deal-breaker.

This is totally fine and can be done at a later time during one-time scan (though I would create another "feature request" issue so it won't get lost)

Though I'm not sure about the actual issue IDs. (SZT[a-z]{2}\d{5}) is mentioned in the PR (and below) and as example SZTab00001 -- could you elaborate on issue IDs? Are they actually upper-lower-case mixed and the lower-case serves as a separator somehow?

The key format is documented in the issue management doc, section 1.4. The ORG prefix is whatever sztab.org.code is configured to at installation time — for the test env that's SZT."