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 namespace or an organization you administer.

Before forking a repository into an organization, forker will check membership and outside collaborator status for the user requesting the fork. When the addUser option is enabled, forker will automatically invite the specified user to become a member of the organization where the fork has been requested.

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.

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.

💡 Note: 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 }}

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

Example: tremor-rs

The name of the GitHub repository you wish to fork.

Example: tremor-runtime

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

Example: wayfair-contribs

The GitHub account for the person requesting the fork.

💡 Note: 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

When used in combination with the org and user inputs, the addUser option will automatically invite a specified GitHub user to the destination organization if they are not already a member.

💡 Note: The email invitation will be sent from whichever account is used to authenticate the GitHub action and fork the requested repository, meaning there must be sufficient permissions to invite outside users to the organization.

Example: true

Default: false

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"

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

uses: wayfair-incubator/[email protected]
with:
  token: ${{ secrets.ACCESS_TOKEN }}
  repo: tremor-runtime
  owner: tremor-rs
  user: lelia

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

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

If you are automating forking on behalf of a GitHub organization, you may wish to leverage the optional addUser and licenseAllowlist params:

uses: wayfair-incubator/[email protected]
with:
  token: ${{ secrets.ACCESS_TOKEN }}
  repo: tremor-runtime
  owner: tremor-rs
  org: wayfair-contribs
  user: lelia
  addUser: true
  licenseAllowlist: "0bsd\napache-2.0\nmit"

💡 Tip: Please use node v9.x or later, as well as an npm-compatible version of typescript.

Install the node dependencies:

npm install

Build the TypeScript code and package it for distribution:

npm run build && npm run package

Run the Jest unit tests:

💡 Note: 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
  ✓ action throws error without required inputs (2 ms)

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.4

💡 Note: 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.

You can now validate the action by referencing ./ in a workflow in your repo (see test.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! ✅

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated. For detailed contributing guidelines, please see CONTRIBUTING.md.

Distributed under the MIT License. See LICENSE for more information.

This GitHub Action was adapted from the typescript-action template, with additional project content curated with 💜 by Wayfair.

For more information about Wayfair's Open Source Program Office, check out wayfair.github.io 🎉