Repository files navigation

Protected Workflows is aGithub application. Its goal is to cancelunauthorized workflow runs.

• What Is the Purpose of This Repository
• Features
• How Does This Application Work
  • When is a Workflow Run "Unauthorized"?
• Configuration
  • Rule
  • Best Practices
• Usage
• Examples & Scenarios

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

1. Cancelunauthorized workflow runs
2. Write configuration using YAMLwith anchors & aliases support.
3. Combine and mix the following parameters to authorize workflow runs:
   1. The user name
   2. Whether the triggering user is:
      • Acollaborator (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")

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 not a singlerule authorized the workflow run.

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

The YAML may contain two top level properties:

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

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

Paths:

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-workflowsevents:# 'pull_request' is the Github event name.# '&pull_request' is a YAML anchorpull_request:&pull_request# Authorize any user when package.json or anything under .github folder was not changed.    -trustAnyone:truepaths: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:truepaths: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:falsetrustCollaborators:falsetrustedUserNames:[]

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

• 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 usinganchors 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...)

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