Mirror upstream H5P
===================

The mirror stage clones every upstream H5P content-type repository
into the hosting Bitbucket workspace, detaching the pipeline from
GitHub availability. It runs twice in the package's life: once at
project init, and periodically to absorb upstream changes.

Prerequisites
-------------

- A ``GITHUB_TOKEN`` with read access to ``h5p/`` on GitHub. Dropped
  in ``.github-token`` or exported in the environment.
- Bitbucket credentials for the hosting workspace. Dropped in
  ``.bitbucket-credentials`` as::

      BITBUCKET_USERNAME=...
      BITBUCKET_APP_PASSWORD=...

- ``BITBUCKET_WORKSPACE`` and ``BITBUCKET_PROJECT`` set in the
  environment or passed to the Make targets.

Initial mirror
--------------

Run once to bootstrap the mirror repositories on Bitbucket::

    make mirror-init

Under the hood this invokes
``byteb4rb1e.sphinxcontrib.h5p.utils.pkg.h5porg.repository mirror init``,
which creates one Bitbucket repo per upstream H5P content type and
pushes each upstream default branch.

Refresh
-------

After the initial mirror exists, keep it current with::

    make mirror-sync

The sync fetches upstream refs and pushes them to the Bitbucket
mirror. New upstream tags become visible to the next ``make index``
run; see :doc:`add-content-type` for the follow-on steps when a new
content type appears upstream.

Regenerate the index
--------------------

Every mirror refresh should be followed by::

    make index

so ``data/package-index.json`` reflects the current ref set. The
index is the single source of truth for the bootstrap stage.
