GitHub Issues

project managementissue trackinggitopen sourcedevelopment integration

Project Management Tool

GitHub Issues

Overview

GitHub Issues is an issue tracking system integrated with GitHub. It links with pull requests, project boards, and milestones to provide bug and feature request management directly integrated into development workflows. Widely used as the de facto standard for open source projects, it can be closely integrated with CI/CD pipelines through GitHub Actions integration.

Details

GitHub Issues is fully integrated with Git repositories, seamlessly connecting code changes with issue management. Issues, Pull Requests, and Project Boards work together to provide the most familiar workflow for developers.

Key Features

Git Integration: Automatic linking with commits, branches, and pull requests
Project Boards: Visual Kanban-style project management
Milestones: Release management and progress tracking
Label System: Flexible categorization and filtering
Templates: Consistent issue and PR creation
Mention Features: Enhanced team member communication
GitHub Actions Integration: Automation and CI/CD integration
REST/GraphQL API: Rich automation and customization options

Target Projects

Open source projects
GitHub-hosted software development
Agile development teams
Small to medium-scale development projects

Pros and Cons

Pros

Complete integration with GitHub ecosystem
Standard usage in open source projects
All basic features available for free
Low learning curve for developers
Powerful API, Webhook, and GitHub Actions integration
Markdown support for easy technical documentation

Cons

Lacks complex project management features
Interface can be difficult for non-technical users
No time tracking or resource management features
Limited custom fields
Limited enterprise features
Requires Git repository (cannot be used standalone)

Reference Pages

Code Examples

Basic Setup

# Install GitHub CLI
# macOS
brew install gh

# Windows
winget install GitHub.cli

# Authentication
gh auth login

# Clone repository
gh repo clone owner/repo
cd repo

# Create issue
gh issue create --title "Bug fix" --body "Detailed description"

Project Creation

# Create project board (GitHub CLI)
gh project create --title "Sprint 1" --body "Progress management for Sprint 1"

# Create issue template
mkdir -p .github/ISSUE_TEMPLATE
cat > .github/ISSUE_TEMPLATE/bug_report.yml << 'EOF'
name: Bug Report
description: Submit a bug report
title: "[Bug]: "
labels: ["bug", "triage"]
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 with you if we need more info?
      placeholder: ex. [email protected]
    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 (Default)
        - 1.0.1
        - 1.0.0
    validations:
      required: true
EOF

Issue Management

# Issue operations
gh issue create \
  --title "Implement user authentication" \
  --body "Implement user authentication using OAuth2.0" \
  --assignee "@me" \
  --label "enhancement,backend" \
  --milestone "v1.0"

# Update issue
gh issue edit 123 \
  --title "New title" \
  --body "Updated description" \
  --add-label "priority:high" \
  --remove-label "priority:low"

# List issues
gh issue list --state open --assignee "@me" --label "bug"

# View issue details
gh issue view 123 --comments

# Close issue (from commit)
git commit -m "fix: resolve login screen bug

Fixes #123"

Workflow Configuration

# .github/workflows/issue-automation.yml
name: Issue Automation

on:
  issues:
    types: [opened, labeled]
  issue_comment:
    types: [created]

jobs:
  auto-assign:
    runs-on: ubuntu-latest
    if: github.event.action == 'opened'
    steps:
      - name: Auto-assign to project
        uses: actions/[email protected]
        with:
          project-url: https://github.com/orgs/company/projects/1
          github-token: ${{ secrets.GITHUB_TOKEN }}

  auto-label:
    runs-on: ubuntu-latest
    if: contains(github.event.issue.body, 'bug')
    steps:
      - name: Add bug label
        uses: actions/github-script@v6
        with:
          script: |
            github.rest.issues.addLabels({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              labels: ['bug', 'triage']
            })

  stale-issues:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/stale@v8
        with:
          stale-issue-message: 'This issue has been inactive for 30 days. Please reopen if needed.'
          close-issue-message: 'Automatically closing due to 60 days of inactivity.'
          days-before-stale: 30
          days-before-close: 60

Reporting Features

// GitHub REST API - Get statistics
const { Octokit } = require('@octokit/rest');

const octokit = new Octokit({
  auth: process.env.GITHUB_TOKEN
});

// Repository statistics
async function getRepositoryStats(owner, repo) {
  // Number of open issues
  const openIssues = await octokit.rest.issues.listForRepo({
    owner,
    repo,
    state: 'open',
    per_page: 1
  });

  // Number of closed issues (last 30 days)
  const thirtyDaysAgo = new Date(Date.now() - 30 * 24 * 60 * 60 * 1000);
  const closedIssues = await octokit.rest.issues.listForRepo({
    owner,
    repo,
    state: 'closed',
    since: thirtyDaysAgo.toISOString(),
    per_page: 100
  });

  // Label statistics
  const labelStats = {};
  for (const issue of openIssues.data) {
    for (const label of issue.labels) {
      labelStats[label.name] = (labelStats[label.name] || 0) + 1;
    }
  }

  return {
    openCount: openIssues.data.length,
    recentlyClosed: closedIssues.data.length,
    labelStats
  };
}

// Milestone progress
async function getMilestoneProgress(owner, repo, milestoneNumber) {
  const milestone = await octokit.rest.issues.getMilestone({
    owner,
    repo,
    milestone_number: milestoneNumber
  });

  const total = milestone.data.open_issues + milestone.data.closed_issues;
  const progress = total > 0 ? (milestone.data.closed_issues / total) * 100 : 0;

  return {
    title: milestone.data.title,
    progress: Math.round(progress),
    openIssues: milestone.data.open_issues,
    closedIssues: milestone.data.closed_issues,
    dueDate: milestone.data.due_on
  };
}

Team Collaboration

# .github/workflows/slack-notification.yml
name: Slack Notifications

on:
  issues:
    types: [opened, closed]
  pull_request:
    types: [opened, closed, merged]

jobs:
  notify:
    runs-on: ubuntu-latest
    steps:
      - name: Notify Slack
        uses: 8398a7/action-slack@v3
        with:
          status: ${{ job.status }}
          custom_payload: |
            {
              attachments: [{
                color: '${{ github.event.action == 'opened' ? 'good' : 'warning' }}',
                title: '${{ github.event.issue.title || github.event.pull_request.title }}',
                title_link: '${{ github.event.issue.html_url || github.event.pull_request.html_url }}',
                text: '${{ github.event.action }} by ${{ github.actor }}',
                fields: [{
                  title: 'Repository',
                  value: '${{ github.repository }}',
                  short: true
                }, {
                  title: 'Labels',
                  value: '${{ join(github.event.issue.labels.*.name, ', ') }}',
                  short: true
                }]
              }]
            }
        env:
          SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}

# Project board automation
- name: Add to project board
  uses: actions/[email protected]
  with:
    project-url: https://github.com/orgs/company/projects/1
    github-token: ${{ secrets.ADD_TO_PROJECT_PAT }}
    labeled: bug,enhancement
    label-operator: OR