Skip to content

Latest commit

 

History

History
152 lines (130 loc) · 6.45 KB

README.md

File metadata and controls

152 lines (130 loc) · 6.45 KB
Raw

Protected Workflows

Protected Workflows is a Github application. Its goal is to cancel unauthorized workflow runs.

Table of Contents

What Is the Purpose of This Repository

This repository is the offical place to view the documentation and report issues regarding Protected-Workflows.

Features

  1. Cancel unauthorized workflow runs
  2. Write configuration using YAML with anchors & aliases support.
  3. Combine and mix the following parameters to authorize workflow runs:
    1. The user name
    2. Whether the triggering user is:
      • A collaborator (requires "admin" or "write" permission).
      • A member of the organisation (If the repository is owned by an organisation)
      • Coming Soon - A member of a certain team (Note: teams feature is limited to organisation/enterprise repositories)
    3. Changed files paths (Limited to workflow runs triggered by "push", "pull_request" or "pull_request_target")

How Does This Application Work

Whenever a workflow run is triggered the application will be notified by github, and will use the application
configuration to authorize the workflow run. Unauthorized workflow runs will be canceled.

When Is a Workflow Run "Unauthorized"?

When not a single rule authorized the workflow run.

Configuration

Configuration is to be written to a file using YAML, and stored within the repository root under .github/protected-workflows.yml.

The YAML may contain two top level properties:

  • "events" which is a map between Github event names and rules
  • "anyEvent" which will be used as a fallback rule when event specific rules are undefined

Rule

A "Rule" is an object made up of the following properties:

Property Description Type Default
trustAnyone Authorize workflow runs triggered by any actor boolean false
trustCollaborators Authorize workflow runs triggered by collaborators boolean false
trustOrgMembers Authorize workflow runs triggered by organisation members boolean false
trustedUserNames Authorize workflow runs triggered by predefined user names string[] []
paths Authorize workflow runs by changed paths. Can only be used with "push", "pull_request" and "pull_request_target" events Paths Paths

Paths:

Property Description Type Default
allowed What paths may be changed string[] []
disallowed What paths may not change. Glob patterns are supported string[] []

Complete example:

# "events" is a map between Github events and rules.
# possible event names can be seen at https://docs.github.com/en/actions/reference/events-that-trigger-workflows
events:
  # 'pull_request' is the Github event name.
  # '&pull_request' is a YAML anchor
  pull_request: &pull_request
  
    # Authorize any user when package.json or anything under .github folder was not changed.
    - trustAnyone: true
      paths:
      	disallowed:
          - ".github/**"
          - "package.json"
    
    # Authorize "bot" user when CHANGELOG.md is the only changed file.
    - trustedUserNames:
        - "bot"
      paths:
        allowed:
          - "CHANGELOG.md"

    # Authorize collaborators when package.json is the only changed file.
    - trustCollaborators: true
      paths:
        allowed:
          - "package.json"

  # Reference the "pull_request" anchor to reuse its configuration
  # Read about "pull_request_target" in this blog post:
  # https://github.blog/2020-08-03-github-actions-improvements-for-fork-and-pull-request-workflows/
  pull_request_target: *pull_request

# 'anyEvent' value is a rule, and will be used when an event specific configuration is not set.
# It is automatically added in case it was not explictly set and it does not supports the 'paths' property.
anyEvent:
  trustAnyone: false
  trustCollaborators: false
  trustedUserNames: []

Attention: Workflow runs will be cancelled only if all rules deemed the workflow is unauthorized

Best Practices

  • Make sure only specific users are allowed to change the configuration file: .github/protected-workflows.yml. Example

  • Use the same rules for "pull_request", "pull_request_target" & "push". (Avoid repeating yourself by using anchors and aliases)

  • Identify build, release and dependency manifest files and limit who can change them to specific users

    Example of what such files may be are:

    • Files under the .github/workflows directory
    • Release Scripts
    • A Dockerfile
    • Dependencies files (package.json, package-lock.json, build.gradle etc...)

Usage

  1. Install the app
  2. Create a configuration file using the above guidelines and store it within the repository root under .github/protected-workflows.yml