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.
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 withforker
.
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.
💡 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
noruser
inputs are specified,forker
will default to forking the repository into your own GitHub account. Similarly, if onlyuser
is provided without an accompanyingorg
, forker will ignore the field, since users cannot create forks on behalf of other users, only GitHub organizations.
Example: lelia
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 therepo
. You can optionally combine this with thepromoteUser
option to grant the useradmin
permissions on the forkedrepo
.🚨 Warning: If the user is not a GitHub
org
member,forker
will exit without forking the repository.
Example: true
Default: false
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 elevatedadmin
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 withcheckUser
, 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 settingcheckUser
totrue
.
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"
This parameter can be used to target a GitHub Enterprise Server instance instead of https://github.com.
Example: https://my-private.github-server.com
A string representing the HTTPS URL of the newly-forked repository.
Example: "https://github.com/wayfair-contribs/tremor-runtime"
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
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
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"
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
💡 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 thetoken
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
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 forncc
, 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 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! ✅
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 🎉