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. 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

In Minds, open Settings → API Keys and create a key for this repository.
In GitHub, save the key as an Actions secret named MINDS_API_KEY at repository or organization level.
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

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.
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.

All integrations

Minds is part of