⑂ forker

March 13, 2024 · View on GitHub

GitHub Action to automate fork creation. This action uses octokit.js and the GitHub API to automatically create a repository fork, either in your personal GitHub account or a GitHub organization that you administer.

If the checkUser option is enabled, forker will check the specified GitHub organization membership status for the user requesting the fork. If the user is already an organization member, forker will proceed to fork the repo, and then optionally grant the user admin permissions when using in combination with the promoteUser option. If the user is not an organization member, forker will exit without forking the repository, and display an error.

For legal and compliance reasons, organizations or individuals can choose to provide an optional licenseAllowlist to compare against the license of the repository being forked. If the license key returned by the GitHub API is not found within the provided allowlist, forker will exit without forking the repository, and display an error.

Inputs

`token` (string, required)

The GitHub API token you wish to use for automating fork creation. If you are using GitHub encrypted secrets, you should reference the variable name you have defined for your secret.

💡 Tip: Ensure the token you are using has sufficient permissions to fork repositories into your intended destination (either an organization or individual user account). In particular, the builtin GITHUB_TOKEN has read-only permissions for repository forks, and therefore may not provide sufficient privileges for use with forker.

Example: ${{ secrets.ACCESS_TOKEN }}

`owner` (string, required)

The owner of the GitHub repository you wish to fork. Can be an organization or individual user account.

Example: tremor-rs

`repo` (string, required)

The name of the GitHub repository you wish to fork.

Example: tremor-runtime

`org` (string, optional)

The name of the destination GitHub organization where you wish to fork the specified repository.

Example: wayfair-contribs

`user` (string, optional)

The GitHub account for the person requesting the fork.

💡 Tip: This is only required if you are managing a GitHub organization, and wish to associate a specific user with the fork request. If neither org nor user inputs are specified, forker will default to forking the repository into your own GitHub account. Similarly, if only user is provided without an accompanying org, forker will ignore the field, since users cannot create forks on behalf of other users, only GitHub organizations.

Example: lelia

`checkUser` (boolean, optional)

Enforces existing membership for a specified user in a specified GitHub org.

💡 Tip: If the user is already a GitHub org member, forker will proceed to fork the repo. You can optionally combine this with the promoteUser option to grant the user admin permissions on the forked repo.

🚨 Warning: If the user is not a GitHub org member, forker will exit without forking the repository.

Example: true

Default: false

`promoteUser` (boolean, optional)

Grants GitHub org members admin permissions on the repo they wish to fork.

💡 Tip: If the requesting user only intends to make upstream contributions to the repo they wish to fork, it is very likely that they will not require elevated admin privileges. That said, if there is an eventual desire to truly fork off and deviate substantially from the originating project, this option helps give users better control over their project and maintainership.

🚨 Warning: If the promoteUser option is not used in combination with checkUser, GitHub users who are not currently GitHub org members may still receive elevated permissions for a repository fork within your organization. If this is an unacceptable degree of risk, you may wish to strictly enforce GitHub org membership by additionally setting checkUser to true.

Example: true

Default: false

`licenseAllowlist` (optional, string)

A newline-delimited ("\n") string representing a list of allowed license keys for the repository being forked. If the license key returned by the Licenses API is not found within the licenseAllowlist, forker will not fork the repository, and instead exit with a warning.

💡 Tip: You can always reference this directory if you need a comprehensive list of license keys, beyond the commonly-used licenses returned from GET /licenses in the GitHub REST API.

Example: "0bsd\napache-2.0\nmit"

`targetInstanceUrl` (optional, string)

This parameter can be used to target a GitHub Enterprise Server instance instead of https://github.com.

Example: https://my-private.github-server.com

Outputs

`forkUrl` (string)

A string representing the HTTPS URL of the newly-forked repository.

Example: "https://github.com/wayfair-contribs/tremor-runtime"

Usage

Typical

In most cases, you'll want to use the latest stable version (eg. v0.0.6):

uses: wayfair-incubator/forker@v0.0.6
with:
  token: ${{ secrets.ACCESS_TOKEN }}
  repo: tremor-runtime
  owner: tremor-rs
  user: lelia

Development

If you're actively developing a new feature for the action, you can always reference a specific commit SHA (eg. a694606ff02c8ba2654865adeb7a6d2053b34afa):

uses: wayfair-incubator/forker@a694606ff02c8ba2654865adeb7a6d2053b34afa
with:
  token: ${{ secrets.ACCESS_TOKEN }}
  repo: tremor-runtime
  owner: tremor-rs
  user: lelia

Advanced

If you are automating the creation of forks on behalf of a GitHub organization with many users, you may wish to leverage the optional checkUser, promoteUser, and licenseAllowlist params:

uses: wayfair-incubator/forker@v0.0.6
with:
  token: ${{ secrets.ACCESS_TOKEN }}
  repo: tremor-runtime
  owner: tremor-rs
  org: wayfair-contribs
  user: lelia
  checkUser: true
  promoteUser: true
  licenseAllowlist: "0bsd\napache-2.0\nmit"

Target a GitHub Enterprise Server

Create a fork in your own GitHub Enterprise Server:

uses: wayfair-incubator/forker@a694606ff02c8ba2654865adeb7a6d2053b34afa
with:
  token: ${{ secrets.ACCESS_TOKEN }}
  repo: tremor-runtime
  owner: tremor-rs
  user: lelia
  targetInstanceUrl: https://my-private.github-server.com

Developing

💡 Tip: Please use node.js v17.x or later, as well as TypeScript v4.x or later.

Install the node.js dependencies:

npm install

Build the TypeScript code and package it for distribution:

npm run build && npm run package

Run the Jest unit tests:

💡 Tip: Before running any tests locally which require authenticating against the GitHub API, please ensure you've defined a valid token for the environment variable INPUT_TOKEN in your preferred shell (or shell profile), eg: export INPUT_TOKEN="my_github_api_token_value". This is functionally equivalent to defining an input value for the token parameter in your GitHub Action's workflow YAML configuration.

$ npm test

 PASS  __tests__/main.test.ts
  ✓ forker action runs with env inputs (631 ms)

Convenience command to run all npm scripts:

npm run all

Publishing

Actions are run from GitHub repos so we will checkin the packed dist/ folder.

Then run ncc and push the results:

npm run package
git add dist
git commit -a -m "prod dependencies"
git push origin releases/v0.0.6

💡 Tip: We recommend using the --license option for ncc, which will create a license file for all of the production node modules used in your project.

Your action is now published! 🚀

See the versioning documentation for more details.

Validation

You can now validate the action by referencing ./ in a workflow in your repo (see build.yml)

uses: ./
with:
  path: ./
  token: ${{ secrets.ACCESS_TOKEN }}
  ref: ${{ github.event.pull_request.head.sha }}
  repo: tremor-runtime
  owner: tremor-rs
  user: lelia

See the Actions tab to view runs of this action! ✅