Package Exports

@auto-it/protected-branch
@auto-it/protected-branch/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@auto-it/protected-branch) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

`protected-branch` Plugin

Handle GitHub branch protections and avoid running auto with an admin token.

Prerequisites

This plugin still needs a Personal Access Token (PAT), but only for a standard user with write permission on your repository. No need to have an admin user.

That also means that you are able to enforce all branch protection requirements for Administrators of your Organization.

When enforcing CodeOwners, this user or a team must be designated as Owner/Co-Owner of released files.

Installation

This plugin is not included with the auto CLI installed via NPM. To install:

npm i --save-dev @auto-it/protected-branch
# or
yarn add -D @auto-it/protected-branch

Usage

Add the protected-branch plugin to the list in .autorc.

No config example:

{
  "plugins": [
    "protected-branch"
    // other plugins
  ]
}

Fully-configured example:

{
   "plugins": [
      [
         "protected-branch",
         {
            "reviewerToken": "redacted", // Probably better idea to set it in `PROTECTED_BRANCH_REVIEWER_TOKEN` environment variable
            "releaseTemporaryBranchPrefix": "protected-release-",
            "requiredStatusChecks": ["check-1", "check-2"]
         }
      ]
      // other plugins
   ]
}

Configuration

How to handle branch protection

The plugin's intent is to handle branch protections, without the need to use an administrator's privileges and/or if you don't want to use an administrator token in our workflow.

An example usage in a repository where we want to have the following protected branch configuration:

branch-protection-part-1 branch-protection-part-2

Create a bot account in this org (auto-release-bot@org.com).
Create a PAT with this bot user and give it repo permissions.
On the repository, create a GitHub actions secret with the previously created PAT.
On the repository, grant write access to the bot account.

When using CodeOwners, on the repository, for each released asset, let the bot account be owner and/or co-owners of each asset.

# Automatically released files must be also owned by our automation @bots team
package.json    @org/owner-team auto-release-bot@org.com
CHANGELOG.md    @prg/owner-team auto-release-bot@org.com

In your build process .yml, be sure to add the PROTECTED_BRANCH_REVIEWER_TOKEN environment variable, and set it to the secret you created previously:

permissions:
 # Needed to create PR statuses/checks
 checks: write
 statuses: write
 # Needed to push git tags, release
 contents: write
...
 # On auto shipit job step
 - name: Release
   env:
     PROTECTED_BRANCH_REVIEWER_TOKEN: ${{ secrets.<<YOUR-GITHUB-ACTIONS-SECRET-NAME>> }}
   run: yarn shipit

Ship it!

Limitations

This plugin is not yet ready to:

Handle more than 1 review requirement
Dynamically list required status checks on target protected branch

@auto-it/protected-branch