Minds for GitHub Actions: Research Review action guide

Minds is an end-to-end platform for commercial synthetic research. The Minds Research Review action brings it into GitHub workflows: prepare a reviewable Study plan for proposed copy that lives in your repository, ask an existing Audience one question, or collect a Study's progress and summary into the job summary.

Availability and requirements

The action is published as Minds Research Review in GitHub Marketplace. This guide covers release v1.0.0, referenced as minds-ai-co/minds-research-action@v1. The source code and complete input contract are public in the minds-research-action repository.

You need a GitHub repository with Actions enabled and a Minds account with API access. The action calls the hosted Minds MCP server at https://getminds.ai/mcp. Existing API permissions and usage limits apply. It has no runtime dependencies and requests no GitHub token permission.

Set up

1. In Minds, open Settings → API Keys and create a key for this repository.
2. In GitHub, save the key as an Actions secret named MINDS_API_KEY at repository or organization level.
3. Add a workflow that uses the action. This example prepares a plan for proposed homepage copy, using the Study ID stored in the repository variable MINDS_PANEL_ID:

name: Research review

on:
  workflow_dispatch:

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: minds-ai-co/minds-research-action@v1
        with:
          api-key: ${{ secrets.MINDS_API_KEY }}
          operation: plan-study
          panel-id: ${{ vars.MINDS_PANEL_ID }}
          request: >-
            Prepare a concept test covering clarity, relevance, objections,
            credibility, and concrete improvements.
          stimulus-file: docs/proposed-homepage-copy.md
          stimulus-label: Proposed homepage copy
          study-locale: en

4. Run the workflow, then review the saved draft in Minds and start the research there when it is ready.

Operations

The action's inputs use the MCP names: a Group is a saved Audience and a Panel is a Study.

Version 1 does not run a structured Study plan. Confirming a saved plan stays an explicit decision in Minds. ask-group does start research and uses the connected account's allowance, so run it only where that is intended. The question is shown to respondents; keep workflow or model instructions out of it.

Inputs and outputs

For plan-study, put the research objective in request and the material respondents should see in either stimulus or stimulus-file, not both. A stimulus file must stay inside the checked-out workspace and is limited to 20 KB. study-locale accepts en, es, fr, de, zh, tr, ar, ja, or ko.

Every run writes a readable result to the GitHub job summary. The outputs are result-json (the complete result, omitted when larger than 500 KB), panel-id, draft-plan-id, revision, and workspace-url. Use them in later steps, for example to post the Minds link on a pull request. Results of ask-group arrive asynchronously: read them in a later run with get-panel-status or get-panel-summary.

Security

• Pass the API key only through the api-key input from a GitHub Actions secret. The action masks it and keeps it out of logs, outputs, summaries, and files.
• Do not use the action with pull_request_target to evaluate untrusted fork content while repository secrets are exposed.
• Pin production workflows to a release tag or a full commit SHA.

Troubleshooting

• 401 or authentication error: check that the secret contains a current Minds API key; see API authentication.
• Study or Audience not found: use an exact ID, or run list-groups to check the saved Audience names for the account behind the key.
• Missing result-json: the result exceeded 500 KB; read it from the job summary or in Minds.
• Plan-limited or rate-limited responses: check the account's API access and usage allowance, and see API errors and limits.

Synthetic findings provide early, directional evidence; they do not replace representative human research for high-stakes decisions. Browse all integrations or see the MCP tools reference.