github-workflow

SKILL.md

GitHub Workflow Best Practices

You are an expert in GitHub workflows, including pull requests, code reviews, GitHub Actions, issue management, and repository best practices.

Core Principles

Use pull requests for all code changes to enable review and discussion

Automate workflows with GitHub Actions for CI/CD

Maintain clear issue tracking and project management

Follow security best practices for repository access and secrets

Document repositories thoroughly with README and contributing guidelines

Pull Request Best Practices

Creating Effective Pull Requests

Keep PRs small and focused

One feature or fix per PR

Aim for under 400 lines of changes when possible

Split large features into stacked PRs

Write descriptive PR titles

Use conventional commit style: feat: add user authentication

Be specific about what the PR accomplishes

PR Description Template

## Summary
Brief description of changes and motivation.

## Changes
- Bullet points of specific changes made

## Testing
- How the changes were tested
- Steps to reproduce/verify

## Related Issues
Closes #123

## Screenshots (if applicable)

Link related issues

Use Closes #123 or Fixes #123 to auto-close issues

Reference related issues with #123

Stacked Pull Requests

For complex features, use stacked PRs:

Create a base feature branch

Create subsequent PRs that build on each other

Merge in order from base to top

Keep each PR small and reviewable

Code Review Guidelines

As a Reviewer

Review promptly - Respond within 24 hours when possible

Be constructive - Focus on improvement, not criticism

Ask questions - Seek to understand before suggesting changes

Prioritize feedback:

Blocking: Security issues, bugs, breaking changes

Important: Performance, maintainability

Nice-to-have: Style preferences, minor improvements

Comment Conventions

Use prefixes to indicate comment severity:

blocking: Must be addressed before merge

suggestion: Recommended improvement

question: Seeking clarification

nit: Minor style or preference (optional to address)

praise: Positive feedback on good code

Example Review Comments

blocking: This SQL query is vulnerable to injection.
Please use parameterized queries.

suggestion: Consider extracting this logic into a separate
function for better testability.

nit: Prefer `const` over `let` here since this value
is never reassigned.

Approval Criteria

All blocking comments addressed

Tests pass

CI/CD checks pass

At least one approval from code owner

GitHub Actions

Workflow Best Practices

Use workflow templates

name: CI
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'
      - run: npm ci
      - run: npm test

Cache dependencies

- uses: actions/cache@v4
  with:
    path: ~/.npm
    key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}

Use reusable workflows

jobs:
  call-workflow:
    uses: ./.github/workflows/reusable.yml
    with:
      environment: production
    secrets: inherit

Set appropriate timeouts

jobs:
  build:
    timeout-minutes: 10

Security in Actions

Use secrets for sensitive data

Pin action versions with SHA: uses: actions/checkout@a5ac7e51b41094c92402da3b24376905380afc29

Limit GITHUB_TOKEN permissions

Review third-party actions before use

permissions:
  contents: read
  pull-requests: write

Issue Management

Issue Templates

Create .github/ISSUE_TEMPLATE/ with templates:

Bug Report:

---
name: Bug Report
about: Report a bug
labels: bug
---

## Description
Clear description of the bug.

## Steps to Reproduce
1. Step one
2. Step two

## Expected Behavior
What should happen.

## Actual Behavior
What actually happens.

## Environment
- OS:
- Browser:
- Version:

Feature Request:

---
name: Feature Request
about: Suggest a new feature
labels: enhancement
---

## Problem
Describe the problem this feature would solve.

## Proposed Solution
Describe your proposed solution.

## Alternatives Considered
Other approaches you've considered.

Labels

Use consistent labels:

bug, enhancement, documentation

good first issue, help wanted

priority: high, priority: medium, priority: low

status: in progress, status: blocked

Repository Management

Branch Protection Rules

Configure for main branch:

Require pull request reviews

Require status checks to pass

Require conversation resolution

Require signed commits (optional)

Restrict force pushes

CODEOWNERS File

# .github/CODEOWNERS
* @default-team
/docs/ @docs-team
/src/api/ @backend-team
*.js @frontend-team

Security Best Practices

Enable security features

Dependabot alerts and updates

Code scanning with CodeQL

Secret scanning

Manage secrets properly

Use repository or organization secrets

Rotate secrets regularly

Never commit secrets to code

Access control

Use teams for permissions

Follow principle of least privilege

Audit access regularly

Automation Recommendations

Auto-merge for Dependabot

name: Dependabot auto-merge
on: pull_request

permissions:
  contents: write
  pull-requests: write

jobs:
  dependabot:
    runs-on: ubuntu-latest
    if: github.actor == 'dependabot[bot]'
    steps:
      - name: Auto-merge minor updates
        run: gh pr merge --auto --squash "$PR_URL"
        env:
          PR_URL: ${{ github.event.pull_request.html_url }}
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Release Automation

Use semantic-release or release-please for automated releases based on conventional commits.