Skip to content
havit-internalPublic

About

Organization-wide defaults for havit-internal

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

havit-internal/.github

Organization-wide defaults for repositories in the havit-internal organization.

GitHub treats a repo named exactly .github in an org specially: any repo that does not define its own version of these files falls back to what lives here. That gives the whole org consistent issue templates, PR templates, community health files, and a canonical label set with zero per-repo work.

What lives here

.github/
├── ISSUE_TEMPLATE/
│   ├── feature.yml          ← Outcome-level container; rolls up Stories
│   ├── bug_report.yml       ← "Something broken" in dev, staging, or production
│   ├── user_story.yml       ← A user-facing slice of work
│   ├── task.yml             ← Implementation slice — a piece of a Story
│   └── config.yml           ← Disables blank issues
├── pull_request_template.md ← Issues / Refs — see QA convention below
├── labels.yml               ← Source of truth for sev:*/meta labels (work type is an Issue Type, not a label; workflow status is the Work status issue field, not a label)
└── workflows/
    ├── qa-routing.yml        ← Reusable workflow — see "PR convention" below.
    ├── issue-status-sync.yml ← Reusable workflow — issue closed ⟷ Work status Done, both directions; reopened → In progress
    ├── pr-linked-status.yml  ← Reusable workflow — PR linked to issue → Work status In progress
    ├── subissue-rollup.yml   ← Reusable workflow — child Task/Bug status rolls up to parent Story/Feature
    └── label-sync.yml        ← Runs centrally — see "Label sync" below. CI still planned.

workflow-templates/          ← Ready-made wrappers for the reusable workflows — see "Adding the wrappers to a repo"
├── qa-routing.yml            (+ .properties.json)
├── issue-status-sync.yml     (+ .properties.json)
├── pr-linked-status.yml      (+ .properties.json)
└── subissue-rollup.yml       (+ .properties.json)

plugins/
└── gh-issue-templates/      ← Claude Code plugin — see "Claude Code plugin" below

Related org repos

Repo Role
havit-internal/.github Fallback files: issue templates, PR template, .github/labels.yml. Reusable workflows also live here, under .github/workflows/ (qa-routing.yml, issue-status-sync.yml, pr-linked-status.yml, subissue-rollup.yml, and label-sync.yml built; CI still planned).
havit-internal/002.HFW-NewProjectTemplate-Blazor GitHub template repo for new Blazor projects. Not org-wide — covers the Blazor stack specifically, not every repo type.

Templates from this repo are inherited by every repo in the org that does not define its own. Workflow files are not inherited — a reusable workflow defined here still has to be called explicitly from a thin wrapper in each consuming repo (uses: havit-internal/.github/.github/workflows/<name>.yml@main). Those wrappers can be added through the GitHub UI (Actions → New workflow) — see "Adding the wrappers to a repo" below. No separate workflows repo is needed for this — reusable workflows can be called from any repo, including this one. If workflow versioning or ownership ever needs to diverge from the templates/labels here, split them out then; until that's a real need, keeping everything in one repo is simpler.

Adding the wrappers to a repo

Each wrapper is published as an org workflow template (workflow-templates/ at the root of this repo). In the consuming repo, go to Actions → New workflow, find the By havit-internal section, and click Configure on QA routing, Issue status sync, or PR-linked issue status, then commit. Nothing to copy by hand, and the uses: path to the reusable workflow can't be mistyped.

workflow-templates/*.yml is the single source for the wrapper YAML — the sections below describe what each workflow does and link there instead of repeating it. Without the UI, copy the file into the consuming repo's .github/workflows/ under the same name. The wrappers take no inputs. Where the jobs run is decided org-wide by one variable — see "Which runner" below.

Issue template inheritance — the gotcha

Fallback is all-or-nothing per repo. As soon as a repo defines any issue template of its own (even one), the org defaults stop applying to that repo entirely — they do not merge with local templates.

Prefer keeping repos with zero local templates so they inherit the full set defined here.

Feature → Story → Task hierarchy

  • Feature — outcome-level container. Not implemented directly; holds Stories.
  • Story — a vertical, user-facing slice of a Feature. The unit that gets planned and delivered.
  • Task — an implementation-level piece of a Story.
  • Bug — unplanned work; can reference a parent Story or Feature but doesn't require one.

Every template is a single required Description box — free-form plain text, no sections, no checklists, no prefilled content. Write whatever the issue needs; nothing is asked for that the author doesn't want to give.

Parent/child linking is manual — mention the parent issue number in the description, and use GitHub's sub-issue UI where it helps navigation.

Work type vs. labels

Work type (feature / story / task / bug) is not a label — it's set via GitHub's native org-level Issue Types (org Settings → Issue types), which sync to every repo automatically with no workflow needed. Task, Bug, Feature, and Story are all configured and enabled on the org, matching the type: key each issue template sets.

The issue templates set their Issue Type via the top-level type: key in each .github/ISSUE_TEMPLATE/*.yml file (not the labels: key). labels.yml below is only for things Issue Types and the Work status field don't cover: severity and triage/meta labels. Workflow status itself is not a label — it's the org-wide Work status issue field (see "QA routing workflow" below).

No template presets needs-triage (or any other label), and that's deliberate — don't add labels: back. A label listed in a template is applied by GitHub a moment after the issue is created, as a separate step that ignores the label picker, so deselecting it in the new-issue dialog doesn't stick: it reappears on the created issue. Untriaged is better expressed as a filter — is:issue no:assignee — and needs-triage stays in labels.yml for whoever wants to set it by hand.

Label sync

.github/labels.yml is the canonical list for severity (sev:*) and meta labels (needs-triage, blocked, skip-qa, etc.) — everything that isn't a work type or a workflow status. .github/workflows/label-sync.yml applies it to every repo in the org automatically — on push to main when .github/labels.yml changes, on a weekly schedule (catches repos created since the last sync), and on demand (workflow_dispatch). Do not create ad-hoc labels in individual repos — edit this file and open a PR here instead.

Unlike the other workflows in this repo, label-sync.yml is not reusable / per-repo-opt-in — it runs centrally, only here, and pushes out to every repo in the org. No wrapper needed anywhere else.

It's non-destructive: creates labels that don't exist yet in a repo, and updates the color/description of ones that already match by name, but never deletes or otherwise touches a label that isn't in .github/labels.yml — a repo's own ad-hoc labels are left alone.

It needs an org-level secret, ORG_LABEL_SYNC_SECRET — a fine-grained PAT (or GitHub App token) with Issues: Read and write across all repositories in the org. The default GITHUB_TOKEN won't work here: it's scoped only to the repo the workflow runs in, and this workflow writes labels to every other repo in the org. To set it up:

  1. Create a fine-grained PAT. Resource owner: havit-internal. Repository access: All repositories (so newly created repos are covered without reconfiguring the token). Permissions → Repository permissions → Issues: Read and write.
  2. If the org requires approval for fine-grained PATs, an org owner needs to approve it before it's usable.
  3. Add it as an organization-level Actions secret (Org Settings → Secrets and variables → Actions → New organization secret), named ORG_LABEL_SYNC_SECRET, with repository access limited to havit-internal/.github (the only repo that needs it).
  4. Fine-grained PATs expire (max 1 year) — note the expiry and plan to rotate it, or move to a GitHub App later if this becomes long-lived.

PR convention: Closes/Fixes/Resolves vs Refs

The qa-routing workflow (see below) piggybacks on GitHub's own closing keywords instead of inventing a separate one. Use Closes #N, Fixes #N, or Resolves #N — anywhere in the PR description, one or several comma-separated (Fixes #10, #11) — for every issue this PR fixes. Here the keyword only links the issue: our repos have GitHub's auto-close of linked issues on merge turned off, so the merge does not close it.

On merge, qa-routing sets the org-wide Work status issue field to Ready for QA and assigns everyone in .github/QAOWNERS; the issue stays open. It gets closed only when it's actually done — when QA sets Work status to Done, issue-status-sync closes it (and closing it by hand as completed sets Done). If QA rejects the fix, set Work status back to In progress. The one exception is a skip-qa issue, which qa-routing sets to Done and closes itself — see below.

You don't have to type a keyword at all — linking an issue via the PR's Development panel (the "Link a pull request"/"Link an issue" UI) works identically. The workflow reads GitHub's own resolved closingIssuesReferences for the PR, the same data that panel displays, so a manually linked issue is picked up exactly like a Fixes #N in the text — no body parsing involved.

  • Closes #N / Fixes #N / Resolves #N in the body, or a manual link in the Development panel — This PR fixes issue N. On merge, set to Ready for QA by qa-routing; stays open until QA moves it to Done.
  • Refs #N — Related issue, no action. Cross-link only, not routed to QA (plain text mentions never appear in closingIssuesReferences unless linked one of the two ways above).

QA routing workflow

.github/workflows/qa-routing.yml is a reusable workflow. It does not run on its own — each consuming repo needs a thin wrapper that triggers it on merge: workflow-templates/qa-routing.yml. Add it through the UI: Actions → New workflow → By havit-internal → Configure.

Which runner

The four reusable workflows (qa-routing, issue-status-sync, pr-linked-status, subissue-rollup) run on our self-hosted Windows runners by default — labels self-hosted, windows, qa-routing. To move them to GitHub-hosted ubuntu-slim (e.g. while the self-hosted runners are down), set the organization variable ISSUE_WORKFLOWS_RUN_ON_HOSTED_RUNNER to 1 (Organization settings → Secrets and variables → Actions → Variables, scoped to all repositories). Any other value, or no variable at all, means self-hosted. The switch applies to new runs only: jobs already queued for a self-hosted runner stay queued, so cancel and re-run them. Nothing changes in the consuming repos — the wrappers pass no inputs. label-sync is not affected; it always runs on GitHub-hosted ubuntu-slim (it runs only in this repo, takes about a minute, and needs yq and a checkout).

Self-hosted runners need Actions Runner v2.327.1 or newer. These workflows run actions/github-script v9 (and label-sync runs actions/checkout v7), which refuse to start on an older runner — the job fails before any script of ours executes. Hosted runners like ubuntu-slim are always new enough, so this only matters for the self-hosted runners.

What it does on merge:

  1. Reads the PR's closingIssuesReferences (GraphQL) — the same resolved list GitHub shows in the PR's Development panel, covering both Closes/Fixes/Resolves #N text and manually linked issues. No matches → no-op.
  2. For each linked issue, sets the org-wide Work status issue field (single select) to Ready for QA via the setIssueFieldValue GraphQL mutation — a single-select field only ever holds one value, so this always replaces whatever Work status was there before (no stacking, unlike labels). Exception: an issue labeled skip-qa goes straight to Done and gets closed instead — see below.
  3. Assigns everyone listed in that repo's .github/QAOWNERS — see below (skipped for skip-qa issues, since there's no QA pass to assign).
  4. Leaves a comment on the issue linking back to the merged PR.

skip-qa label: for issues with nothing for a tester to verify (purely technical work — refactors, dependency bumps, internal tooling). Label the issue skip-qa before the PR merges, and qa-routing sets Work status straight to Done and closes the issue itself, instead of Ready for QA plus a QAOWNERS assignment. skip-qa is defined in labels.yml alongside the other meta labels.

.github/QAOWNERS format (lives in each consuming repo, not here): one GitHub username per line, @ optional, # for comments, blank lines ignored:

# QA owners for this repo — all are assigned on every merge
@alice
@bob

If a repo has no QAOWNERS file, the workflow still sets Work status to Ready for QA but leaves the issue unassigned (logged as a warning in the workflow run) — so repos can adopt this incrementally rather than needing QAOWNERS set up before merges work at all.

Work status field IDs: the workflow references the Work status field and its Ready for QA and Done options (the latter used by the skip-qa path above) by GraphQL node ID (single-select fields are set by option ID, not name). Those IDs are hardcoded as constants in qa-routing.yml — if the field or an option is ever deleted and recreated (even with the same name), it gets new IDs and the workflow needs updating. Look them up via repository.issueFields for any repo in the org (the field is org-wide, so it shows up the same everywhere).

Issue status sync workflow

.github/workflows/issue-status-sync.yml is a reusable workflow that keeps an issue's open/closed state and its Work status field in sync, in both directions. Wrapper: workflow-templates/issue-status-sync.yml. Add it through the UI: Actions → New workflow → By havit-internal → Configure.

What it does:

  • Issue closed as completed → sets Work status to Done. A close with any other reason (won't-fix, duplicate) is left alone — "Done" implies actual completion, not "not planned". Exception: if a merged PR closed the issue and the repo also runs qa-routing, Work status is left to qa-routing (Ready for QA, or Done for skip-qa). Both workflows fire on the same merge, so without this the issue could end up Done and skip QA, depending on which run finished last. "Runs qa-routing" means a workflow file on the default branch has a uses: line calling the qa-routing.yml reusable workflow; a repo without one still gets Done on a PR close. Only a PR in the same repo counts — qa-routing skips cross-repo issues, so an issue closed by another repo's PR still gets Done here.
  • Issue reopened → if Work status is Done or Ready for QA, sets it to In progress — typically QA rejecting a fix. Any other status is left as is, and so is an issue that was closed again before the run got to it.
  • Work status set to Done (the field_added activity type, which GitHub fires whenever any issue field value is set or changed) → closes the issue as completed.

Each direction checks the other side's current state before acting (already Done? already closed?), so triggering one doesn't bounce back and forth with the other — it settles after at most one harmless extra run.

PR-linked issue status workflow

.github/workflows/pr-linked-status.yml is a reusable workflow that moves an issue's Work status to In progress as soon as a PR is linked to it — same closingIssuesReferences detection as qa-routing.yml (body keyword or Development panel link, either way). Wrapper: workflow-templates/pr-linked-status.yml. Add it through the UI: Actions → New workflow → By havit-internal → Configure.

It skips issues whose Work status is already Ready for QA or Done, so it never walks status backward (e.g. a small follow-up PR after QA rejected it shouldn't undo that progress). Caveat: a PR linked purely through the Development panel, with no further edit to the PR itself, won't trigger this workflow until the PR's next opened/edited-type event — there's no dedicated webhook event for "issue linked via panel" alone.

Sub-issue status rollup workflow

.github/workflows/subissue-rollup.yml is a reusable workflow that rolls a parent issue's Work status up from its children — Task/Bug statuses roll up to their Story, Story statuses roll up to their Feature. It's the only workflow here that acts on the Feature → Story → Task hierarchy; the other three act on one issue at a time. Wrapper: workflow-templates/subissue-rollup.yml. Add it through the UI: Actions → New workflow → By havit-internal → Configure.

The rollup rule (child → parent only, never parent → child):

State of the children Parent Work status
No sub-issues left alone — behaves as a normal issue under the other workflows
All still Backlog/unset left alone
Any started (In progress / Ready for QA / Done), not all Done In progress
All children Done Done, and the parent is closed as completed

"Done" means the child's Work status is Done — not merely closed. A task closed by a merged PR but still at Ready for QA (what qa-routing sets on merge) counts as started, not done, so merging the last task can't mark a Story done before QA has signed off. This does assume the repo also runs issue-status-sync, which is what sets Work status to Done when an issue is closed as completed.

Key behaviours:

  • Native sub-issues only. Rollup reads GitHub's issue.parent / issue.subIssues, so children must be linked with the sub-issue UI/API, not just a #123 mention in the description. The manual-mention convention in "Feature → Story → Task hierarchy" above is fine for navigation but is invisible to this workflow.
  • Self-contained — it closes the parent and climbs the tree itself. A field written with the default GITHUB_TOKEN does not trigger further workflow runs, so rollup can't lean on issue-status-sync to close a parent it marks Done, nor on a re-fired rollup to climb Story → Feature. It therefore closes a Done parent itself and walks the ancestor chain within the same run (each climb keeps its own visited set to stop it looping). So the last child reaching Done closes the Story and rolls that up into the Feature in one go.
  • Forward-only. It only ever advances a parent toward Done, matching pr-linked-status.yml's "never walk backward" stance. A child reopening under an already-closed parent does not reopen the parent — that's left to a human (or to issue-status-sync, if the parent itself is reopened). This is the deliberate cost of having no Story-level QA step; if it ever bites, a Ready for QA intermediate for parents can be added without a redesign.
  • "Not planned" children are excluded. A child closed as not planned or duplicate (whatever its Work status) is dropped from the rollup, so it can neither block the parent from reaching Done nor count as progress.
  • Same-repo only. Sub-issues can cross repositories, but — like qa-routing / pr-linked-status — a parent or child in another repo is skipped: its events fire in that repo, and a run here can only read and write issues in its own.

What drives it: the wrapper triggers on a child's closed, reopened and field_added (a Work status change) — the status/close events that actually move the rollup; a reopen matters because it brings a child closed as not planned back into the count without any field write — plus the sub_issue_* / parent_issue_* events, which catch a child being re-parented without any status change. The Work status field IDs are the same hardcoded field/option node IDs as the other workflows — see the note under "QA routing workflow".

Status set by the other workflows reaches the rollup via a dispatch. issue-status-sync, pr-linked-status and qa-routing write Work status with GITHUB_TOKEN, so their writes fire no field_added — a PR opening (In progress), a merge (Ready for QA / skip-qa Done) or a close (Done) would otherwise never reach the parent. After each such write they send a work-status-changed repository_dispatch listing the issues, which GITHUB_TOKEN can raise, and the rollup wrapper listens for it. Because it fires after the write, it also closes the race where a manual close reaches the rollup before issue-status-sync has set the child to Done. Sending it needs contents: write in those three wrappers (the templates now grant it). A repo that keeps contents: read still works — the dispatch is skipped with an info line — it just doesn't get automated status rolled up. The reusable workflows deliberately declare no permissions: of their own, so they inherit whatever the wrapper grants and an older wrapper keeps starting.

Concurrency caveat: two status changes on different children of the same parent can run concurrently and race on the parent's status — one run computes Done while another computes In progress, and the forward-only guard only sees its own snapshot, so the later writer can still move the parent back within that narrow window. Each run recomputes from the parent's live children, so the next event on that parent self-corrects; a hard guarantee would need a per-parent lock that GitHub Actions can't express. Low-volume issue traffic makes this rare, but it's a known limitation rather than a solved problem.

Rollout — pilot first. Like the other reusable workflows, this does nothing until a consuming repo adds the wrapper. Add it to one repo first (Actions → New workflow → Sub-issue status rollup → Configure), switch that repo's issue-status-sync / pr-linked-status / qa-routing wrappers to contents: write, and exercise the hierarchy there — start a child → the Story goes In progress; finish all children → the Story goes Done and closes; same again up to the Feature — and only then add it to the other repos. Nothing in this repo changes to onboard another repo; it's wrapper-only, per repo.

Project template: kanban on Work status, not project Status

Projects' built-in Status field is per-project — every project gets its own copy, nothing keeps them consistent across repos, and none of the workflows above can write to it. The org-wide Work status issue field is the opposite: defined once, one value per issue, readable from every project and repo, and already driven by qa-routing, issue-status-sync, and pr-linked-status. A board here should therefore draw its columns from Work status and leave the project's own Status unused.

That is supported: an org issue field added to a project behaves like any project single-select — it can be the board's column field as well as its Group by (swimlane) axis, and dragging a card between columns writes the issue field itself, which the workflows above then see.

Template shape

One org-level project, configured once, then Settings → Templates → Copy as template so it shows up under New project.

Fields on the project:

Field Source Role
Work status org issue field board columns — Backlog / Ready / In progress / Ready for QA / Done
Type native Issue Type swimlanes — Feature / Story / Task / Bug
Priority org issue field Urgent / High / Medium / Low — sort within a column
Iteration project iteration field, 1-week sprint scoping — the @current / @next views filter on it
Parent issue, Sub-issues progress built-in Feature → Story → Task roll-up
Status built-in project field delete it — or hide it in every view if the project won't let it go — so nobody maintains two competing statuses

Work status is org-visibility All, but Priority is Org only, and org-only issue fields are hidden in projects that are public or internal — so either keep the project private or flip Priority to All in the org's issue field settings.

Views, in tab order — boards for moving work day to day, tables for planning, triage and bulk edits (inline edits, paste down a column, sort and group without dragging cards). Every view is sorted by Priority, and every view except All work is also filtered to is:issue:

View Layout Filter / setup Who, when
Current iteration board iteration:@current; columns Work status, swimlanes Type whole team, daily — the default view
QA queue table work-status:"Ready for QA" — exactly what qa-routing sets on merge; shows Iteration, Linked pull requests testers
Next iteration table iteration:@next; shows Type, Priority, Assignees, Sub-issues progress sprint planning
Backlog & triage table no:iteration -work-status:Ready,"In progress","Ready for QA",Done — i.e. Work status empty or Backlog, no iteration triage: set type, priority, Work status, then an iteration
Bugs table type:Bug; shows Labels (for sev:*), Iteration, Work status deciding which bugs go into this or the next sprint
Features table type:Feature; shows Sub-issues progress, Iteration product and leads: are each Feature's Stories moving?
All work table no filter at all — deliberately includes PRs and drafts; grouped by Work status overview and search, the catch-all

The Backlog filter excludes the other Work status values because a filter can't express "empty or Backlog" directly — if Work status gains an option, add it to that exclusion list. There's no roadmap view: its date axis can't be set through the API, so add one by hand on a project that wants a timeline.

Add the org fields from a table view (+ in the header → Add field → the org issue fields are listed alongside project fields); set column field and Group by from the board's view-options menu. Pick filter values from the suggestion dropdown rather than typing qualifiers — GitHub writes the qualifier itself, including for multi-word field names.

The views were created through the REST API (POST /orgs/{org}/projectsV2/{number}/views; a classic token or gh login needs the project scope, a fine-grained token or GitHub App needs the organization Projects read-and-write permission), which takes name, layout, filter, visible fields, sort, column field and Group by. Two gaps: it silently drops Group by Type (the native Issue Type isn't exposed as a groupable field), so the swimlanes on Current iteration are set by hand; and there's no call to edit an existing view's layout settings — GraphQL updateProjectV2View only changes name, filter and visible fields. deleteProjectV2View does work, which is how the default Table / Board / Roadmap views were removed.

Why the views are filtered to is:issue

Issue fields only populate on issues owned by this org. Pull requests, draft issues, and issues from other orgs have no Work status at all and would pile up in a "No Work status" column. is:issue keeps PRs and drafts off the board; PRs are still visible on the cards through Linked pull requests. is:issue does not exclude issues from other orgs, though — if one is added to the project it still shows up without a Work status. Auto-add only pulls from this org's repos, so that takes adding one by hand.

Issues themselves can still lack a value. Nothing sets a Work status or an Iteration when an issue is created — the templates here set only a type: — so a fresh issue never reaches Current iteration; it shows up in Backlog & triage. That view is the intake lane: everything in it with an empty Work status is untriaged, and triage means setting type, priority and Work status, then an iteration.

Which built-in project automations still apply

The built-in workflows that move work forward — "when an issue or PR is closed, set Status to Done" and the same for merged PRs, both on by default — write the project's Status field, which a project built this way doesn't use. They go inert, and nothing is lost: the three reusable workflows in this repo do that job one level down, on the issue itself, so it holds for issues in no project at all.

The built-in workflows that don't touch Status are unaffected and still worth using — auto-add (pull items from a repo into the project) above all, plus auto-archive.

What a copy carries, and what it doesn't

Copying a project (or creating one from the template) brings the views, the fields and their values, draft issues, insights, and configured workflows — except auto-add workflows, which are never copied. Every new project therefore needs its own "auto-add items from repo X" workflow wired up by hand.

The copy does keep its board columns bound to the issue field Work status — it does not fall back to a project-local single select. GitHub's docs don't state this either way; it was checked by hand on the first project created from the template.

Claude Code plugin

This repo doubles as a Claude Code plugin marketplace (.claude-plugin/marketplace.json). It currently ships one plugin, gh-issue-templates, with a skill that creates GitHub issues matching the actual template a target repo renders (including the all-or-nothing inheritance gotcha above) — field order, labels, and native Issue Type — instead of a freeform title/body.

Install once, works in any repo:

/plugin marketplace add havit-internal/.github
/plugin install gh-issue-templates

Changing something here

Everything in this repo affects every repo in the org. Open a PR, get review from at least one other maintainer, and merge. Changes take effect immediately for any repo that doesn't override.

About

Organization-wide defaults for havit-internal

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors