Appearance
Linking pull requests
A pull request links itself to Crosdesk work when it mentions that work. You don't paste anything: write the reference where you would write it anyway, and the link appears.
This needs your workspace's GitHub App, which an administrator sets up once (GitHub). Without it, you can still paste a pull request's URL onto a task by hand.
Where to write it
Crosdesk reads four places, every time the pull request changes:
- The branch name —
tsk-12-fix-depot-filter,feature/TSK-12. The cheapest habit: name the branch after the task and you never think about it again. - The title —
TSK-12: Fix the depot filter. - The description —
Fixes TSK-12, or anywhere in the text. - Any commit message in the pull request.
Upper or lower case, it makes no difference. The reference has to stand on its own: TSK-12 and fix-tsk-12 count, but XTSK-12 and TSK-12a don't.
What you can link
| Write | Links to |
|---|---|
TSK-12 | Task 12 |
PRJ-4 | Project 4 |
REL-3 | Release 3 — its own pull requests, like the version bump |
ISS-9 | Issue 9, under a feature step or in a release's QA |
FTR-7 | Feature 7's current phase: the first one not done, or the last if all are |
FTR-7/PH-2 | Phase 2 of feature 7 |
FTR-7/PH-2/HLD | The step labelled HLD in that phase |
Every one of these shows its reference beside its pull requests, with a copy button. A task shows its reference beside its title.
Step labels in a branch name. ftr-7/ph-2/hld-fix-login links the HLD step: when the phase has no step labelled HLD-FIX-LOGIN or HLD-FIX, Crosdesk tries the shorter label. So you can add a description after the label, as you would after a task number. Phases are numbered in the order they were added, so PH-2 is the second one.
A step reference links the step only, not its phase as well. The phase is one click away.
A repository two workspaces share
Task numbers belong to a workspace: Acme's TSK-12 and Kerala Water Authority's TSK-12 are different tasks. When one repository is connected to two workspaces, a bare TSK-12 there could mean either. So on a shared repository, only the qualified form links:
TSK-12@acmeacme is the workspace's name in its address — /w/acme/…. The qualified form works on every repository, shared or not, so if in doubt, use it. The copy button offers both.
Admin → GitHub shows which of your repositories are shared.
What a link shows
A linked pull request shows its title and its status, and stays current as the pull request changes. GitHub in place of a person's name means the link came from a reference, not from someone pasting it.
Status
A pull request is in one of: Draft, Open, Review requested, Changes requested, Gate failed, Approved, Merged or Closed. When more than one applies, the badge shows the one that matters most: merged or closed, then a failing gate, then changes requested, review requested, approved, draft and open.
From GitHub. A pull request the workspace's app reports gets its status from GitHub: opened, draft, merged and closed; a review requested, approved or with changes requested; and a failing check or commit status as Gate failed, clearing when every check on the latest commit passes. A new commit starts its checks afresh. Gate status needs two permissions an app made before them does not have — see GitHub.
By hand. Choose the status badge — Set status on a pull request with none — and pick Open, Review requested, Gate failed, Merged or Closed. Use it for GitLab and Bitbucket links, links pasted without the app, or to say what GitHub cannot see yet. Anyone who can see something the pull request is linked to can set it; it is recorded in the audit log. The menu says who set it and when. On a pull request GitHub reports, GitHub's next update replaces it.
A status is the pull request's, not the link's: set on a task, it shows on its project and its release too. A pull request nobody has given a status and GitHub has not reported shows none — not Open — because nothing is known.
Removing a link
Take the reference out of the branch, title, description or commits, and the link goes the next time the pull request changes. A link someone pasted by hand is never removed this way. If you remove a GitHub-made link in Crosdesk while the reference is still in the pull request, it comes back with the pull request's next change.
What it never does
- It writes nothing to GitHub. No comments, no labels, no status checks. The app can only read — pull requests, reviews, checks and commit statuses. A status set by hand stays in Crosdesk.
- It does not move tasks. A merged pull request doesn't mark a task done.
- It shows nothing you can't see. A link sits on the task, and who can see the task is still decided by its department.
- An unknown number links nothing. A pull request mentioning
TSK-99999, a phase the feature doesn't have, or a step label the phase doesn't have, creates nothing and reports nothing.