--- title: "Minds for GitHub Actions: Research Review action… | Minds" canonical_url: "https://getminds.ai/guide/integration-github-action" last_updated: "2026-10-02T21:16:26.055Z" meta: description: "Use the Minds Research Review action from GitHub Marketplace to plan reviewable Studies, ask an Audience a question, and read results from a GitHub workflow." "og:description": "Use the Minds Research Review action from GitHub Marketplace to plan reviewable Studies, ask an Audience a question, and read results from a GitHub workflow." "og:title": "Minds for GitHub Actions: Research Review action… | Minds" "twitter:description": "Use the Minds Research Review action from GitHub Marketplace to plan reviewable Studies, ask an Audience a question, and read results from a GitHub workflow." "twitter:title": "Minds for GitHub Actions: Research Review action… | Minds" --- Minds October 1, 2026·Minds Team # **Minds for GitHub Actions: Research Review action guide** Minds Research Review is a GitHub Action published in GitHub Marketplace. It connects a workflow to the Minds MCP server with an API key stored as a secret. The default operation saves a Study plan for review and does not start research. 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](https://github.com/marketplace/actions/minds-research-review). 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](https://github.com/minds-ai-co/minds-research-action). You need a GitHub repository with Actions enabled and a Minds account with API access. The action calls the hosted [Minds MCP server](https://getminds.ai/mcp/overview) 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](https://getminds.ai/?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 ```1. 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. | Operation | Required inputs | Effect | | --- | --- | --- | | `list-groups` | none | Lists the account's saved Audiences. `search-query` filters by name. | | `plan-study` (default) | `panel-id` or `panel-name`, `request` | Saves a reviewable Study draft without starting research. | | `ask-group` | `group-id` or `group-name`, `question` | Starts a private, asynchronous Study with one Audience. | | `get-panel-status` | `panel-id` or `panel-name` | Returns the Study's composition and progress. | | `get-panel-summary` | `panel-id` or `panel-name` | Reads the summary, or refreshes it with `refresh-summary: true`. | 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](https://getminds.ai/docs/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](https://getminds.ai/docs/api/errors). Synthetic findings provide early, directional evidence; they do not replace representative human research for high-stakes decisions. Browse [all integrations](https://getminds.ai/guide/integrations) or see the [MCP tools reference](https://getminds.ai/mcp/tools). [~~All integrations~~](https://getminds.ai/guide/integrations) [Minds](https://getminds.ai/)© 2026 Minds. Your target audience. AI-driven and grounded in transparent evidence. Build within minutes. [Minds on X (Twitter)](https://x.com/mindsai_co) [Minds on LinkedIn](https://www.linkedin.com/company/mindsaicompany/) [Minds on Instagram](https://www.instagram.com/getminds.ai/)Minds is part of [![ESOMAR](https://getminds.ai/images/newsroom/logos/esomar-logo.svg)ESOMAR](https://esomar.org/) [![GreenBook](https://getminds.ai/images/newsroom/logos/greenbook.svg)GreenBook Directory](https://greenbook.org/company/Minds) [![Insight Platforms](https://getminds.ai/images/newsroom/logos/insight-platforms.png)Insight Platforms](https://www.insightplatforms.com/platforms/minds/) [![Capterra](https://getminds.ai/images/newsroom/logos/capterra.svg)Capterra](https://www.capterra.com/p/10046203/Minds/) [![G2](https://getminds.ai/images/newsroom/logos/g2.svg)G2](https://www.g2.com/products/minds/reviews) [![CSSDA Best UX Design Award](https://getminds.ai/images/newsroom/logos/cssda-best-ux-award.png)CSSDA Best UX Design Award](https://www.cssdesignawards.com/) [![CSSDA Best Innovation Award](https://getminds.ai/images/newsroom/logos/cssda-best-innovation-award.png)CSSDA Best Innovation Award](https://www.cssdesignawards.com/) [![CSSDA Best UI Design Award](https://getminds.ai/images/newsroom/logos/cssda-best-ui-award.png)CSSDA Best UI Design Award](https://www.cssdesignawards.com/)