GitHub Actions pull request workflow

This guide covers the fundamental aspects of the GitHub pull request workflow, including how to set up and use GitHub Actions to automate checks and how to manage pull requests from forks.

Overview of the pull request workflow

A pull request (PR) allows developers to notify team members about changes they've pushed to a GitHub repository, and then submit those change for feedback. Collaborators can review the set of changes, discuss potential improvements, spot bugs, and once consensus is reached, merge the pull request into the main line of development. This workflow facilitates code review and enhances code quality.

Setting up GitHub Actions for pull requests

GitHub Actions can be configured to automatically run workflows based on pull request activities, such as opening, updating, or closing a pull request. These workflows can perform tasks like building, running tests, and checking coding standards.

1. Run workflows on pull requests

To trigger a workflow when a pull request is made, you need to set the on key in your workflow file (usually .github/workflows/<workflow_name>.yml) to handle pull_request events:

name: CI

on:
  pull_request:
    branches:
      - main

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Install dependencies
        run: npm install
      - name: Run tests
        run: npm test

This example sets up a continuous integration (CI) workflow that runs whenever a pull request is open against the main branch. This example workflow checks out the repository, installs dependencies, and runs tests.

2. Using workflow_run with pull requests

Sometimes, you may want to run a workflow as a result of another workflow's completion. This is useful in situations where you want to ensure a chain of workflows execute in a specific sequence:

on:
  workflow_run:
    workflows: ['CI']
    types:
      - completed

jobs:
  deploy:
    runs-on: ubuntu-latest
    if: ${{ github.event.workflow_run.conclusion == 'success' }}
    steps:
      - uses: actions/checkout@v2
      - name: Deploy
        run: ./deploy.sh

This workflow listens for the completion of the "CI" workflow and runs only if the CI workflow was successful.

3. Troubleshooting: GitHub workflow not running on pull request

If your workflows aren’t triggering on pull requests, check the following:

• YAML syntax: Ensure there are no syntax errors in your .yaml file.
• Branch paths: Make sure the branches specified in the workflow file match the branches used in pull requests.
• Permissions: For pull requests from forks, ensure that workflows are enabled for fork pull requests under the repository's Actions settings.

Managing pull requests from forks

When working with contributions from forks in public projects, GitHub's pull request workflow requires additional considerations:

1. Triggering workflows from forks: By default, workflows triggered by pull_request events run in the context of the base repository on the latest commit of the base branch that the PR targets. This means that certain secrets or write permissions might not be available.

2. Safely testing fork pull requests: You can use the pull_request_target event, which provides a safe environment for handling pull request workflows from forks by running workflows from the base repository with access to its secrets. However, this must be handled carefully to avoid executing untrusted code with elevated permissions:

on:
  pull_request_target:

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v2
        with:
          ref: ${{ github.event.pull_request.head.sha }}
      - name: Run checks
        run: npm test

Best practices for GitHub pull request workflows

• Review workflows regularly: Keep your workflows updated with the latest GitHub Actions features and security practices.
• Minimize use of secrets: Be cautious when using secrets, especially when dealing with pull requests from forks.
• Clear documentation: Document your workflow requirements and guidelines for contributors, especially regarding how pull requests should be structured (e.g., coding standards, commit messages).

The GitHub pull request workflow, augmented with GitHub Actions, provides a robust framework for automating checks and ensuring code quality in collaborative software development.

For further reading on the GitHub pull request workflow see the official GitHub documentation.