GitHub Actions pull request workflow

Kenny DuMez
Kenny DuMez
Graphite software engineer

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.

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.

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.

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:

Terminal
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.

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:

Terminal
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.

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.

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:

Terminal
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
  • 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.

Stay unblocked. Ship faster.
Experience the new developer workflow - create, review, and merge code continuously. Get started with one command.
Get started

Give your PR workflow
an upgrade today

Stack easier | Ship smaller | Review quicker

Or install our CLI.
Product Screenshot 1
Product Screenshot 2