How to Sync GitHub PR Labels With Your Workflow States (Step by Step)

If your testing status lives in a spreadsheet while your code lives on GitHub, the two will always drift apart. This tutorial walks through how to sync GitHub PR labels with your workflow states in KazTrack, so a pull request’s testing status updates automatically and its label changes post comments back to the real GitHub thread. By the end, “tested” and “labeled” will mean the same thing — every time.

What You’ll Build

You’ll connect a project to GitHub, map four workflow states to GitHub label names, and confirm that moving a pull request through the lifecycle updates the labels on GitHub automatically. The four canonical states are:

ready_for_testing → in_progress → passed → failed

Each maps to a GitHub label name of your choosing. When a tester advances a pull request, KazTrack applies the matching label on GitHub and posts a comment to the PR.

Prerequisites

Before you start, make sure you have:

• A KazTrack project (registering auto-provisions one).
• A role with permission to manage GitHub settings and labels — typically owner or manager, or a custom role granting those permissions.
• A GitHub Personal Access Token (PAT) for the bot account that will apply labels and post comments.
• At least one repository connected to the project with an open pull request to test against.

Step 1: Connect GitHub With a PAT

1. In your project, open QA → Settings → GitHub.
2. Paste your GitHub Personal Access Token and the bot username the token belongs to.
3. Save. The PAT is stored encrypted — it’s never shown back to you or returned in API responses.

This token is what authorizes KazTrack to read pull requests, apply labels, and post comments on your behalf. Use a token scoped to the repositories you intend to manage, no more.

Step 2: Add Your Repositories

1. Go to QA → Repositories.
2. Add the GitHub repositories you want to track. They’re scoped to the current project, so each project sees only its own repos.
3. Confirm the pull request list populates under Pull Requests.

If PRs don’t appear, double-check that the PAT’s bot account has access to those repositories.

Step 3: Map Workflow States to GitHub Label Names

This is the core of the sync. Open QA → Labels to configure the label mapping. Each of the four workflow states maps to a GitHub label name:

Workflow state	Example GitHub label
ready_for_testing	QA: Ready
in_progress	QA: Testing
passed	QA: Passed
failed	QA: Failed

You choose the label text — pick names that read clearly on a GitHub PR. A few rules to follow:

• Match exactly. The label name in KazTrack must match the GitHub label string character-for-character (including capitalization and any prefix like QA:).
• Create the labels in GitHub too. If a label doesn’t exist in the repo yet, create it in GitHub’s Labels settings so colors and descriptions are consistent.
• Keep one label per state. Each workflow state maps to exactly one label, so the synced state is unambiguous.

Save the configuration when all four are mapped.

Step 4: Drive a Pull Request Through the Workflow

Now verify the sync end-to-end with a real PR:

1. Open the Pull Requests list and pick a PR currently in ready_for_testing.
2. Claim it and start a testing session. The PR moves to in_progress — and the QA: Testing label appears on the pull request in GitHub.
3. Do your testing. If test cases are attached to the PR, record each result.
4. Set the workflow label to passed (or failed) from KazTrack.
5. Switch to the pull request on GitHub.

You should now see two things on the GitHub PR:

• The label has changed to QA: Passed (or QA: Failed), replacing the in-progress label.
• A comment has posted to the thread reflecting the new state.

That’s the full loop: a state change in KazTrack becomes a label change and a comment on the real pull request.

Step 5: Confirm the Sync Direction and Behavior

A few things worth understanding so the automation never surprises you:

• State changes flow to GitHub. When you advance a PR in KazTrack, the matching label is applied on GitHub and a comment is posted. This keeps the PR thread as the single visible record.
• Labels are how the workflow is expressed. The state isn’t a hidden field — it’s a real GitHub label your whole team (and any GitHub automation) can see.
• Comments give an audit trail. Because each transition posts a comment, anyone reading the PR can reconstruct the testing history without leaving GitHub.

Troubleshooting Common Sync Issues

The label doesn’t change on GitHub. Check that the label name in QA → Labels matches the GitHub label string exactly, and that the label actually exists in that repository.

No comment appears on the PR. Verify the PAT’s bot account has write access to the repository. A read-only token can read PRs but can’t post comments or apply labels.

The PR isn’t showing up in KazTrack. Confirm the repository is added under QA → Repositories and that the bot account can see it.

Permission denied when editing labels. Configuring label mappings requires the labels-management permission. Make sure your role (or a custom role you’ve been assigned) includes it.

A Quick Recap of the Flow

KazTrack state change
   → apply matching GitHub label
   → post comment to the PR thread
   → team sees status on GitHub, no spreadsheet needed

Once this is wired up, your testing status stops being a separate artifact. It becomes part of the pull request itself.

Key takeaways

• To sync GitHub PR labels with your workflow, map each of the four states (ready_for_testing, in_progress, passed, failed) to an exact GitHub label name.
• Advancing a PR in KazTrack applies the label on GitHub and posts a comment — keeping the PR thread as the source of truth.
• Most sync issues come down to label-name mismatches or insufficient PAT permissions.

Ready to stop reconciling status by hand? Set up your label mapping in KazTrack and let every testing state update show up right on the pull request where your team already works.