Automated stat reporting for packtracker.io

Strategies to report your build stats via the following platforms

• GitHub Actions
• CircleCI Orbs

CircleCI Orb

In order to use the CircleCI Orb, you must first opt-in your organization to allow third party orbs within your Organization Security settings.

You can do this by going to Settings > Organization > Security

Setup

Next, you will add our orb to your configuration by declaring it in your CircleCI configuration.

version: 2.1

orbs:
  packtracker: packtracker/[email protected]

Note: If you started using CircleCI prior to 2.1, you must enable pipelines within your project configuration to be able to use the orbs configuration.

Authentication

In order for us to know what project you are reporting stats for, you must send along your packtracker project token. To do this with the CircleCI Orb, you must create a new project environment variable in your CircleCI settings called PT_PROJECT_TOKEN. You can find your packtracker project token in your project's settings.

Configuration

If you are not yet using CircleCI Workflows, you will need to do so. If this is the case, you likely have a single build job in your CircleCI configuration. In order to add the packtracker job to your CI run, you will need to set up a multi-job workflow as seen in this example configuration.

Now that you've declared our orb for use and added your project token, you have access to our report job. You can put this job anywhere inside your existing CircleCI workflows.

workflows:
  version: 2
  your_existing_workflow:
    jobs:
      - build
      - packtracker/report

Or, create a new workflow to run packtracker reporting in parallel.

workflows:
  version: 2
  your_existing_workflow:
    jobs:
      - build
  packtracker:
    jobs:
      - packtracker/report

By default, this base configuration should just work most of the time. If you have a non-standard setup, you can tweak the job with the following 3 optional parameters.

webpack_config

We try and assume your webpack configuration is located in the root of your repository as webpack.config.js

If it is not, you can let us know where it is like so.

workflows:
  packtracker:
    jobs:
      - packtracker/report:
          webpack_config: "./config/webpack/production.js"

For example, this is where the Ruby on Rails webpack configuration is located.

project_root

Sometimes you are trying to track a project within a greater repository, maybe the package.json does not live at the repository root, but in an internal directory. This is common for monorepo configurations like lerna.

workflows:
  packtracker:
    jobs:
      - packtracker/report:
          project_root: "./packages/internal_package"

selected_resource_class

Sometimes your Orb might not have enough resources to complete your webpack build, and you might need to specify a higher resource class.

This is most often surfaced with a nondescript "Killed" message in your build output

Note: Resource classes are a paid feature of CircleCI

workflows:
  packtracker:
    jobs:
      - packtracker/report:
          selected_resource_class: medium+

exclude_assets

There may be assets you wish to exclude from tracking. This options allows you to pass a regular expression string. When this regular expression matches the name of any asset you are producing, it will exclude it from reporting. This simply gets passed along to the webpack stats configuration.

For example:

workflows:
  packtracker:
    jobs:
      - packtracker/report:
          exclude_assets: "main|pack"

This would exclude any assets with the string main or pack in the name.

GitHub Action

Secrets (Required)

• PT_PROJECT_TOKEN - your packtracker.io project token.

Environment variables (Optional)

• WEBPACK_CONFIG_PATH - the relative path to your webpack configuration (if you have one)
• PT_PROJECT_ROOT - the relative path to the directory of your project (containing your package.json file)
• PT_EXCLUDE_ASSETS - This options allows you to set a regular expression string. When this regular expression matches the name of any asset you are producing, it will exclude it from reporting. This simply gets passed along to the webpack stats configuration.

Workflow

A sample .github/workflows/push.yml file might look something like this

on: push
name: packtracker.io
jobs:
  report:
    name: report webpack stats
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@master
    - name: report webpack stats
      uses: packtracker/[email protected]
      env:
        PT_PROJECT_TOKEN: ${{ secrets.PT_PROJECT_TOKEN }}