@cdwr/nx-migrate-action

Nx Migrate

GitHub action that brings automatic Nx migrations to your workspace.

 

Description

This action assures your Nx workspace stays up to date.

When the action runs it will check you local Nx version to see whether there's a new version available. In that case a migration process is triggered and the changes are tested by your test setup.

A pull request is always created for a new version, which can by auto-merged when all tests have passed.

As long as the repository is setup to allow auto-merges

An open pull request for a specific Nx version is considered pending and will block a new pull request from being created for the same version. This is to give a developer some time to fix any breaking changes or to review in case auto-merge is disabled.

On the other hand, when a new Nx version is released the action will automatically close any pending pull requests and create a new one. The pending pull request branches will be deleted.

Usage

Using the action is currently limited to this repository since the package isn't deployed.

- uses: actions/checkout@v4

# Install dependencies and tools...
# Build 'nx-migrate-action' package...

- name: Run Nx migrate
  uses: ./packages/nx-migrate-action
  with:
    token: ${{ secrets.BOT_TOKEN || secrets.GITHUB_TOKEN }}

Permissions

Pull requests

GitHub Actions must be allowed to create pull requests.
This feature should be enabled for the repository in Settings -> General -> Workflow permissions.

Token

A token is a required input to the action, which needs to be able to both read and write to the repository, as well as manage pull requests.

Option 1

Use the default GITHUB_TOKEN and elevate the permissions in the workflow.

permissions:
  contents: write
  pull-requests: write

[!IMPORTANT]

If the pull requests created with this action have status checks triggered via push or pull_request events, then you cannot use the default GITHUB_TOKEN.

This by design to prevent you from accidentally creating recursive workflow runs.

Two workarounds to this limitation.

• Create a Personal Access Token (PAT) as described in Option 2 below.
• Register a GitHub App to authenticate which also is more secure than a PAT.
  Read more about how to register in GitHub App Settings.

Option 2

Generate a Personal Access Token (PAT).

• Classic PAT should have repo and workflow scopes
• Fine-grained PAT should have Contents, Pull requests and Workflows set to Read and write

Add the token to the repository secrets in Settings -> Secrets and variables -> Actions.

Inputs

See action.yaml for descriptions of the inputs.

Additional input details

auto-merge

It will always be false when auto merge isn't enabled in the repository settings.

For major version updates this option is ignored. When it's set to true a comment will be added to the pull request explaining why auto-merge is disabled.

Also when any of tests or e2e is enabled and fail, auto merge will be disabled. A comment will reflect this in the pull request.

check-token

It's not recommended to use this in production since it might block the workflow from running.

committer

Commits can be signed automatically when token is generated from your own GitHub App. You also need to provide the same GitHub App details as the committer.

your-app[bot] <{APP_ID}+your-bot[bot]@users.noreply.github.com>

Read more about GitHub commit signature verification.

skipTests & skipE2e

[!TIP] When status checks have been setup which will affect the created pull request, there's no need to run any tests within the action.

Set skipTests and/or skipE2e to true depending on the nature of the checks.

When base tests are not skipped, the action will run this command

nx run-many -t lint,test,build -c ci

When e2e is not skipped and previous tests did not fail, the action will run this command

nx run-many -t e2e -c ci

[!NOTE] When any of the commands fail, auto merge will be disabled, in case auto-merge was set to true

Development

Running locally with act

GitHub actions can be run locally using act.

By providing a proper PAT the action will be able to run just like it does in the GitHub Actions runner.

Getting started instructions can be found in .github/workflows/README.md.

After act has been installed

Verify that the secrets and variables have the desired values:

• .env.act
• .secrets
• .vars

Run the action:

nx act nx-migrate-action

Miscellaneous

GitHub App Settings

1. Follow the instructions in Register a GitHub App and apply the settings below:

   • Webhook is not needed, so uncheck Activeunder Webhook
   • Select under Repository permissions
     • Contents with Write & Read access
     • Pull requests with Write & Read access
     • Workflows with Write & Read access
   • Select under Organization permissions
     • Members with Read access
       Note! Optional to also be able to use teams in inputs

2. When the app is created, generate a private key and store it securely together with the generated PEM file.

3. Install the app to the repositories you want to run the action in.

4. Create secrets and select which repositories to expose them to.

   • APP_ID: The GitHub App ID
   • APP_PRIVATE_KEY: The private key

   Secret names could be anything you like.

5. Your workflow must be complemented with a new action which will generate a token in run-time.

- uses: actions/create-github-app-token@v1
  id: generate-token
  with:
    app-id: ${{ secrets.APP_ID }}
    private-key: ${{ secrets.APP_PRIVATE_KEY }}

- uses: actions/checkout@v4

# Install dependencies and tools...
# Build 'nx-migrate-action' package...

- name: Run Nx migrate
  uses: ./packages/nx-migrate-action
  with:
    token: ${{ steps.generate-token.outputs.token }}