GitHub Issues and Projects — The 'Fix' Issue That Sat for 6 Months

Every team has a Slack channel where bugs get reported. And lost. GitHub Issues solves this by putting every bug, feature request, and task in a searchable, assignable, labeled database tied directly to the code. GitHub Projects adds prioritization and workflow tracking. The combination is powerful enough for many teams to replace Jira entirely. This guide covers issue templates, labels, project boards with automation, and the incident where a missing triage process led to a 6-month-old security issue becoming a production breach.

Why Track Work Beyond Code?

Git is great for code, but it's terrible for project management. Issues and pull requests don't tell you why a feature was built, who approved it, or whether it's blocked by a dependency. GitHub Issues and Projects fill that gap by providing a structured way to track tasks, bugs, and features alongside your codebase. Without them, teams rely on Slack messages, spreadsheets, or memory—each a recipe for chaos. In production, I've seen teams miss deadlines because a critical bug was discussed in a DM and never logged. GitHub Projects gives you a single source of truth for what's being worked on, why, and by whom. It's not optional; it's how you scale beyond a 2-person team.

name: Bug Report
description: File a bug report
title: "[Bug]: "
labels: ["bug"]
body:
  - type: markdown
    attributes:
      value: |
        Thanks for taking the time to fill out this bug report!
  - type: input
    id: contact
    attributes:
      label: Contact Details
      description: How can we get in touch if we need more info?
      placeholder: ex. email@example.com
    validations:
      required: false
  - type: textarea
    id: what-happened
    attributes:
      label: What happened?
      description: Also tell us, what did you expect to happen?
      placeholder: Tell us what you see!
    validations:
      required: true
  - type: dropdown
    id: version
    attributes:
      label: Version
      description: What version of our software are you running?
      options:
        - 1.0.2
        - 1.0.3
      default: 0
    validations:
      required: true
  - type: textarea
    id: logs
    attributes:
      label: Relevant log output
      description: Please copy and paste any relevant log output. This will be automatically formatted into code.
      render: shell

Setting Up Issue Templates for Consistency

Issue templates are your first line of defense against ambiguity. They force reporters to provide structured information, making triage faster. GitHub supports both Markdown-based templates and YAML-based forms. I prefer YAML forms because they enforce required fields and dropdowns, reducing back-and-forth. For example, a bug report template should include environment details, steps to reproduce, expected vs actual behavior, and logs. In production, I've seen teams waste hours asking 'What version are you on?' because the template didn't require it. Set up templates in .github/ISSUE_TEMPLATE/ and configure them in the repository settings. You can also use config.yml to blank issues and link to a contact channel.

blank_issues_enabled: false
contact_links:
  - name: GitHub Community Support
    url: https://github.com/orgs/community/discussions
    about: Please ask and answer questions here.
  - name: Security Issues
    url: https://github.com/org/security
    about: Please report security vulnerabilities here.

Organizing Work with Labels and Milestones

Labels and milestones are the scaffolding of your project management. Labels categorize issues by type (bug, enhancement), priority (critical, low), or status (needs review, blocked). Milestones group issues toward a specific goal, like a release or sprint. In production, I've seen teams use too many labels (50+) and then ignore them. Stick to a small set: bug, feature, tech-debt, blocked, needs-triage, and priority: critical. Milestones should have a clear due date and description. Use the GitHub API to enforce that issues in a milestone must have a specific label. This prevents 'zombie milestones' that never close.

#!/bin/bash
# Check that all issues in a milestone have a priority label
MILESTONE="v1.0"
gh issue list --milestone "$MILESTONE" --json number,labels | jq -r '.[] | select(.labels[].name | startswith("priority:") | not) | .number' | while read num; do
  echo "Issue #$num missing priority label"
  # Optionally add a default label
  # gh issue edit $num --add-label "priority: medium"
done

GitHub Projects: Kanban Boards That Sync with Issues

GitHub Projects (the new Projects experience) is a kanban board that syncs with issues and pull requests. Unlike the old Projects, the new version is built on a spreadsheet-like table with custom fields, views, and automation. You can create a board with columns like 'To Do', 'In Progress', 'In Review', and 'Done'. Each card is an issue or PR. The killer feature is automation: when a PR is merged, you can automatically move the linked issue to 'Done'. In production, I've seen teams manually drag cards and forget to update status. Automate everything. Use the 'Item added to project' trigger to set default fields like 'Status: To Do'.

name: Project Automation
on:
  issues:
    types: [opened]
jobs:
  add-to-project:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/add-to-project@v0.5.0
        with:
          project-url: https://github.com/orgs/myorg/projects/1
          github-token: ${{ secrets.PROJECT_TOKEN }}
          labeled: bug, feature
          label-operator: OR

Linking Issues to Pull Requests for Traceability

When a PR closes an issue, GitHub automatically links them and moves the issue to 'Done' if configured. This creates an audit trail: you can see exactly which code change resolved which issue. Use keywords like closes #123, fixes #123, or resolves #123 in the PR description. In production, I've seen teams forget to link issues, leading to orphaned PRs that nobody understands. Enforce linking with a branch naming convention (e.g., feature/123-add-login) and a PR template that asks 'Which issue does this close?'. Use GitHub Actions to block PRs without an issue reference.

name: Require Issue Link
on:
  pull_request:
    types: [opened, edited]
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/github-script@v6
        with:
          script: |
            const pr = context.payload.pull_request;
            const body = pr.body || '';
            const linked = /(close|fix|resolve)s?\s+#\d+/i.test(body);
            if (!linked) {
              core.setFailed('PR must link to an issue using keywords like "closes #123".');
            }

Using Custom Fields for Priority, Effort, and Sprint

GitHub Projects' custom fields let you add metadata like priority (High, Medium, Low), effort (story points), sprint iteration, or target release. These fields power views and filters. For example, you can create a view that shows only 'High priority' items in the current sprint. In production, I've seen teams use labels for priority, but labels are messy for sorting. Custom fields are typed (text, number, date, single select) and can be used in automation. Use a 'Sprint' field with a date range to track iterations. Combine with a 'Points' field for velocity tracking. Export the project data to a CSV for reporting.

// Export project items to CSV using GitHub GraphQL API
const { graphql } = require('@octokit/graphql');
const fs = require('fs');

const query = `
  query($owner: String!, $repo: String!, $project: Int!) {
    repository(owner: $owner, name: $repo) {
      projectV2(number: $project) {
        items(first: 100) {
          nodes {
            content {
              ... on Issue {
                title
                number
                state
              }
            }
            fieldValues(first: 10) {
              nodes {
                ... on ProjectV2ItemFieldSingleSelectValue {
                  name
                  field {
                    ... on ProjectV2SingleSelectField {
                      name
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
`;

// Usage: pass owner, repo, project number
// Outputs CSV to stdout

Automating Workflows with GitHub Actions and Project Automation

GitHub Actions can automate almost any project management task: auto-assign issues, add labels based on content, move cards between columns, or send Slack notifications. For example, when a PR is merged, you can automatically close the linked issue and move it to 'Done'. Or when an issue is opened with 'bug' label, auto-assign it to the on-call engineer. In production, I've seen teams manually assign issues and forget to update status. Automate everything that's deterministic. Use the actions/add-to-project action to add issues to a project board. Use actions/github-script for custom logic.

name: Auto Assign Bug
on:
  issues:
    types: [opened, labeled]
jobs:
  assign:
    if: contains(github.event.issue.labels.*.name, 'bug')
    runs-on: ubuntu-latest
    steps:
      - uses: actions/github-script@v6
        with:
          script: |
            const assignees = ['sre-team'];
            await github.rest.issues.addAssignees({
              owner: context.repo.owner,
              repo: context.repo.repo,
              issue_number: context.issue.number,
              assignees: assignees
            });

Reporting and Insights: Measuring Team Velocity

GitHub Projects doesn't have built-in velocity charts, but you can export data and use external tools. Use the GraphQL API to fetch items with custom fields like 'Points' and 'Sprint'. Then calculate velocity as total points completed per sprint. In production, I've seen teams guess velocity and consistently miss commitments. Track actual vs planned points over 3-4 sprints to get a reliable number. Use a simple script to generate a burndown chart. Also track cycle time (time from issue opened to closed) to identify bottlenecks. Share these metrics in a weekly team dashboard.

import requests
import json

# Fetch project items via GraphQL
query = """
query($owner: String!, $repo: String!, $project: Int!) {
  repository(owner: $owner, name: $repo) {
    projectV2(number: $project) {
      items(first: 100) {
        nodes {
          content {
            ... on Issue {
              title
              closedAt
              createdAt
            }
          }
          fieldValues(first: 10) {
            nodes {
              ... on ProjectV2ItemFieldNumberValue {
                number
                field {
                  ... on ProjectV2NumberField {
                    name
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}
"""

# Calculate velocity: sum of points for issues closed in last sprint
# (pseudo-code, requires actual API call)
print("Velocity: 34 points in last sprint")
print("Cycle time: 4.2 days average")

Best Practices for Scaling Across Teams

When multiple teams share a repository, use issue templates with team-specific fields, labels per team (e.g., team:platform), and project boards per team or per initiative. Use the 'Iteration' field for sprints and 'Team' custom field for ownership. In production, I've seen cross-team issues fall through cracks because nobody owned them. Use a shared 'Triage' board where unassigned issues live until a team picks them up. Also, use GitHub's 'Organization Projects' to create cross-repo boards for company-wide initiatives. Enforce a policy that every issue must have a team label and a priority.

name: Feature Request
description: Suggest an idea for this project
title: "[Feature]: "
labels: ["feature"]
body:
  - type: dropdown
    id: team
    attributes:
      label: Team
      options:
        - Platform
        - Frontend
        - Backend
        - Data
    validations:
      required: true
  - type: textarea
    id: description
    attributes:
      label: Description
      placeholder: What problem does this solve?
    validations:
      required: true

Common Pitfalls and How to Avoid Them

Pitfall 1: Over-customization. Too many fields, labels, and workflows confuse the team. Start minimal and iterate. Pitfall 2: Ignoring the board. If the board doesn't reflect reality, people stop using it. Automate status updates and enforce discipline. Pitfall 3: Using issues for everything. Not every conversation needs an issue. Use discussions for open-ended questions. Pitfall 4: No cleanup. Close stale issues after 90 days of inactivity. Use a GitHub Action to auto-close issues with a 'stale' label. In production, I've seen backlogs with thousands of open issues, most of which are irrelevant. Regular grooming is essential.

name: Close Stale Issues
on:
  schedule:
    - cron: '0 0 * * *'
jobs:
  stale:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/stale@v8
        with:
          repo-token: ${{ secrets.GITHUB_TOKEN }}
          stale-issue-message: 'This issue is stale. Please comment if still relevant.'
          days-before-stale: 90
          days-before-close: 14
          stale-issue-label: 'stale'
          exempt-issue-labels: 'pinned,security'