=========================
Using with GitHub Actions
=========================

How to wire asv-perch into GitHub Actions, including marketplace use,
fork-safe commenting, and token-less artifact hand-off.

Marketplace / action pin
------------------------

Publish as a composite Node action:

.. code:: yaml

    - uses: HaoZeke/asv-perch@v1
      with:
        github-token: ${{ secrets.GITHUB_TOKEN }}
        results-path: results/
        metadata-file: results/metadata.txt

Badges and source: `HaoZeke/asv-perch <https://github.com/HaoZeke/asv-perch>`_ · docs
`asv-perch.rgoswami.me <https://asv-perch.rgoswami.me>`_.

Pin a release tag (``~v1`` major or a full semver) in production workflows so
Action updates do not surprise you.

Recipe patterns from ASV
------------------------

Upstream ASV tracks CI / PR-comment workflows in:

- `asv#1448 <https://github.com/airspeed-velocity/asv/issues/1448>`_ -- continuous benchmarking and PR reporting discussions

- `asv#796 <https://github.com/airspeed-velocity/asv/issues/796>`_ -- earlier CI integration recipes and pain points

Those threads cover matrix runners, caching, and where comparison should run.
asv-perch is the comment/presentation piece: run ASV yourself (or let the
action invoke it via ``benchmark-command`` / ``run-prefix``), then hand result
files or pre-computed spyglass text to this action.

Related tools in the same stack:

- `asv-spyglass <https://github.com/airspeed-velocity/asv_spyglass>`_ -- Mann-Whitney aware ``compare`` / ``compare-many`` / ``env-diff``

- `asv-tachyon <https://github.com/HaoZeke/asv_tachyon>`_ -- local/published dashboard (Overview · Compare · Inventory)

Typical split: benchmark job + commenter job
--------------------------------------------

Fork PRs cannot post comments with write ``GITHUB_TOKEN`` from the fork context.
The recommended pattern is:

1. ``pull_request`` workflow: run benchmarks, upload result artifacts

2. ``workflow_run`` (or a same-repo job with write perms): download artifacts,
   run asv-perch, post the PR comment

See `Fork Security <../explanation/fork_security.rst>`_ for the threat
model and a full skeleton.

Token-less comment body (artifact hand-off)
-------------------------------------------

When the job must not use ``pull-requests: write``, set:

.. code:: yaml

    permissions:
      contents: read
      actions: write   # artifact upload only

    jobs:
      prepare-comment:
        runs-on: ubuntu-latest
        steps:
          - uses: actions/download-artifact@v4
            with:
              name: benchmark-results
              path: results/
          - uses: HaoZeke/asv-perch@v1
            id: perch
            with:
              post-comment: false
              upload-comment-artifact: true
              comment-artifact-name: asv-perch-comment
              comment-artifact-path: asv-perch-comment.md
              results-path: results/
              metadata-file: results/metadata.txt
              # github-token omitted / unused when post-comment is false
          - uses: actions/upload-artifact@v4
            with:
              name: ${{ steps.perch.outputs.comment-artifact-name }}
              path: ${{ steps.perch.outputs.comment-body-path }}

The action writes the full GFM body to ``comment-artifact-path`` (also
``comment-body-path`` output) and still writes ``GITHUB_STEP_SUMMARY``. Upload
is a separate ``actions/upload-artifact`` step so the Node action stays small
and does not embed the artifact toolkit.

A trusted job (or a later ``workflow_run`` step with write token) can download
the markdown and post it with ``gh pr comment`` / the GitHub API.

Default behavior is unchanged: ``post-comment: true`` posts/updates the PR
comment when a token is available.

Environment inventory in the comment
------------------------------------

With ``env-diff: true`` (default), the action reads baseline and contender
result JSON and appends ``## Environment inventory`` (added / removed /
version-bumped libraries and runtimes). This is implemented in pure
TypeScript from the result file fields (``requirements``, ``python``, ``params``);
it does not require Python asv-spyglass for the inventory section.

Disable with ``env-diff: false`` if you only want timing tables.

Minimal permissions
-------------------

.. table::

    +-----------------------------------------+-----------------------------------------------------------+
    | Mode                                    | Permissions                                               |
    +=========================================+===========================================================+
    | Post PR comment                         | ``pull-requests: write``, ``issues: write`` (comment API) |
    +-----------------------------------------+-----------------------------------------------------------+
    | Artifact-only (``post-comment: false``) | ``contents: read``, ``actions: write``                    |
    +-----------------------------------------+-----------------------------------------------------------+
    | ``workflow_run`` commenter              | write on base repo token; no fork checkout                |
    +-----------------------------------------+-----------------------------------------------------------+

See also
--------

- `Getting Started <../tutorials/asv_getting_started.rst>`_

- `Configuration <../reference/configuration.rst>`_ (``env-diff``, ``post-comment``, ``upload-comment-artifact``)

- `Pre-computed Output <precomputed_output.rst>`_

- `Fork Security <../explanation/fork_security.rst>`_