diff --git a/.github/workflows/reindex-search.yml b/.github/workflows/reindex-search.yml new file mode 100644 index 000000000..c3e563dbf --- /dev/null +++ b/.github/workflows/reindex-search.yml @@ -0,0 +1,46 @@ +name: Re-index Algolia search + +on: + # The docs deployment pushes gh-pages; GitHub publishes it in this separate + # workflow. Wait for publication so the crawler sees the updated website. + workflow_run: + workflows: [pages build and deployment] + branches: [gh-pages] + types: [completed] + workflow_dispatch: + +permissions: {} + +jobs: + reindex: + name: Start DocSearch crawl + if: >- + (github.event_name == 'workflow_run' && github.event.workflow_run.conclusion == 'success') || + (github.event_name == 'workflow_dispatch' && github.ref == 'refs/heads/main') + runs-on: ubuntu-latest + timeout-minutes: 5 + steps: + - name: Re-index the existing Algolia crawler + env: + ALGOLIA_CRAWLER_ID: ${{ secrets.ALGOLIA_CRAWLER_ID }} + ALGOLIA_CRAWLER_USER_ID: ${{ secrets.ALGOLIA_CRAWLER_USER_ID }} + ALGOLIA_CRAWLER_API_KEY: ${{ secrets.ALGOLIA_CRAWLER_API_KEY }} + shell: bash + run: | + for secret_name in ALGOLIA_CRAWLER_ID ALGOLIA_CRAWLER_USER_ID ALGOLIA_CRAWLER_API_KEY; do + if [[ -z "${!secret_name}" ]]; then + echo "::error::Missing repository secret: ${secret_name}. See README.md for Algolia setup." + exit 1 + fi + done + + # Use the existing crawler's selectors, ranking, and target index. + # API reference: https://www.algolia.com/doc/rest-api/crawler/start-reindex + curl --fail-with-body --silent --show-error \ + --connect-timeout 10 --max-time 60 \ + --retry 2 --retry-delay 10 \ + --request POST \ + --user "${ALGOLIA_CRAWLER_USER_ID}:${ALGOLIA_CRAWLER_API_KEY}" \ + "https://crawler.algolia.com/api/1/crawlers/${ALGOLIA_CRAWLER_ID}/reindex" + + echo "DocSearch crawl requested. Indexing continues asynchronously in Algolia." diff --git a/README.md b/README.md index d1f07c420..a0e08b4fe 100644 --- a/README.md +++ b/README.md @@ -50,3 +50,31 @@ We use GitHub pages for deployment. Use the command below to deploy the reposito ```console GIT_USER= USE_SSH=TRUE npm run deploy ``` + +### Algolia search indexing + +Merging a pull request into `main` runs the documentation deployment workflow, +which pushes the built site to `gh-pages`. After GitHub's **pages build and +deployment** workflow successfully publishes that branch, the **Re-index Algolia +search** workflow requests a fresh crawl of the live site. Failed deployments and +pull request test builds do not trigger a crawl. + +Add these repository secrets under **Settings → Secrets and variables → Actions**: + +| Secret | Value | +| --- | --- | +| `ALGOLIA_CRAWLER_ID` | ID of the existing DocSearch crawler that writes to `AssemblyLine_Documentation`, available in the crawler's dashboard URL. | +| `ALGOLIA_CRAWLER_USER_ID` | Crawler user ID from the [Algolia Crawler settings](https://dashboard.algolia.com/crawler/settings). | +| `ALGOLIA_CRAWLER_API_KEY` | Crawler API key from the same settings page. | + +These are [Crawler API credentials](https://www.algolia.com/doc/rest-api/crawler), +which are separate from the search-only API key in `docusaurus.config.js`. The +account must have access to the Crawler API. The workflow uses the existing +crawler's configuration and requests a crawl through the +[reindex endpoint](https://www.algolia.com/doc/rest-api/crawler/start-reindex). +Indexing continues asynchronously after the workflow succeeds; monitor its +progress in the Algolia crawler dashboard. + +To request another crawl without deploying, run **Re-index Algolia search** from +the GitHub Actions tab with `main` selected. If a required secret is missing, the +indexing workflow fails with a setup message; the website deployment is unaffected.