Lesson 8 · Troubleshooting, checklist, test
Common situations, the set-up checklist, a glossary and the final test.
Goal of this lessonTo solve common situations, check the set-up with a list and test what you learned.
Troubleshooting
| Symptom | What to do |
|---|---|
| A yellow notice on the repository | The token lacks the named permission. Add it on GitHub; the next sync brings that section's history. |
| Sync state 'Error' | Read the error text: the repository was renamed, access was revoked, or GitHub's rate limit. For the rate limit, waiting is enough. |
| A commit did not link | Is the task in the repository's project? Is the commit after the repository's 'Link Keys From' date? If not, link it by hand. |
| The task did not close | Was the PR merged into the default branch? Was the task named in the branch, the title, or with a closing word? Is the project's automation on? |
| No webhook arrives | Look at Webhook Deliveries. No entry: check the webhook URL and secret on GitHub; an 'Error' delivery can be redelivered from GitHub. |
Set-up checklist
- The token or GitHub App reads at least Metadata + Contents.
- The connection is 'Connected', the webhook secret generated.
- The repository is linked to products and projects; the first sync is 'Up to date'.
- The webhook is installed and a delivery shows 'Processed'.
- The project's automation stages are chosen (if wanted).
- Every developer entered their GitHub account on their profile.
- Software products are marked 'Contains Software'.
- Requirements are written and linked; the matrix shows no gap.
Glossary
| Term | Meaning |
|---|---|
| Commit | One recorded change to the code. |
| Branch | A line of work split from the main code. |
| Pull request (PR) | A request to merge a branch; review and checks happen here. |
| Default branch | The product's current code (main, master). |
| Webhook | GitHub telling PORTWARE about an event at once. |
| SBOM | Software bill of materials: dependencies, versions, licences. |
| MoSCoW | Must, Should, Could, Won't priority. |
| DORA | Software delivery performance metrics (frequency, lead time). |
Check yourself
With only Contents and Metadata, what does PORTWARE show?
Branches, commits, releases and the README; a yellow notice for PRs, issues and builds.
What are two ways to close a task from git?
Name the task in the branch or title of a PR merged into the default branch, or write 'Fixes T163'.
Why did an old commit not link?
It predates the repository's 'Link Keys From' date; link it by hand.
What does a red row in the matrix mean?
A gap: the state claims more than the evidence shows.