CI/CD Integration

NeuralRepo’s REST API integrates cleanly into CI/CD pipelines. You can automatically create ideas, update statuses, and track project lifecycle events from GitHub Actions, GitLab CI, or any automation platform.

Note

CI integration requires Pro. Creating an API key is a Pro-gated operation (POST /user/api-keys), and the Settings ▸ Connections tab that manages keys is Pro-only. There is no way to mint a key for CI on the Free plan.

Setting Up API Key Auth for CI

1. Create a dedicated API key. Go to Settings ▸ Connections ▸ API Keys in the NeuralRepo web dashboard, enter a descriptive label like github-actions or ci-pipeline, and click Generate new API key.

   The key is shown once. It starts with nrp_ and is 68 characters long — copy it before closing the dialog. nrepo key create <label> does the same thing from a terminal.

2. Store as a secret. Add the key as a repository secret in your CI provider:

   • GitHub Actions: Repository Settings > Secrets > New repository secret. Name it NEURALREPO_API_KEY.
   • GitLab CI: Settings > CI/CD > Variables. Add NEURALREPO_API_KEY as a masked variable.

3. Use in your pipeline. Reference the secret in your workflow file.

Caution

Never commit API keys to your repository. Always use your CI provider’s secret management.

GitHub Actions Examples

Create an Idea on Release

Automatically capture a new idea when a GitHub Release is published:

name: NeuralRepo — Track Release
on:
  release:
    types: [published]

jobs:
  track-release:
    runs-on: ubuntu-latest
    steps:
      - name: Create NeuralRepo idea
        run: |
          curl -s -X POST "https://neuralrepo.com/api/v1/ideas" \
            -H "X-API-Key: ${{ secrets.NEURALREPO_API_KEY }}" \
            -H "Content-Type: application/json" \
            -d '{
              "title": "Release: ${{ github.event.release.tag_name }}",
              "body": "${{ github.event.release.body }}",
              "tags": ["release", "${{ github.event.repository.name }}"],
              "status": "shipped",
              "source_url": "${{ github.event.release.html_url }}"
            }'

Update Status on Deploy

Mark an idea as shipped when a deployment succeeds:

name: Deploy & Update NeuralRepo
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Deploy application
        run: |
          # Your deployment steps here
          echo "Deploying..."

      - name: Update NeuralRepo idea status
        if: success()
        run: |
          curl -s -X PATCH "https://neuralrepo.com/api/v1/ideas/${{ vars.NEURALREPO_IDEA_ID }}" \
            -H "X-API-Key: ${{ secrets.NEURALREPO_API_KEY }}" \
            -H "Content-Type: application/json" \
            -d '{
              "status": "shipped"
            }'

Tip

Store the NeuralRepo idea ID as a GitHub Actions variable (vars.NEURALREPO_IDEA_ID) so it is easy to update across workflows.

Search and Annotate on PR

Search for related ideas when a PR is opened and post them as a comment:

name: NeuralRepo Context
on:
  pull_request:
    types: [opened]

jobs:
  find-context:
    runs-on: ubuntu-latest
    steps:
      - name: Search NeuralRepo for related ideas
        id: search
        run: |
          RESULT=$(curl -s "https://neuralrepo.com/api/v1/ideas/search?q=${{ github.event.pull_request.title }}&limit=3" \
            -H "X-API-Key: ${{ secrets.NEURALREPO_API_KEY }}")
          echo "result=$RESULT" >> "$GITHUB_OUTPUT"

      - name: Post comment with related ideas
        uses: actions/github-script@v7
        with:
          script: |
            const result = JSON.parse('${{ steps.search.outputs.result }}');
            if (result.results && result.results.length > 0) {
              const ideas = result.results.map(i =>
                `- **#${i.id}**: ${i.title} (${i.status})`
              ).join('\n');
              await github.rest.issues.createComment({
                owner: context.repo.owner,
                repo: context.repo.repo,
                issue_number: context.issue.number,
                body: `## Related NeuralRepo Ideas\n${ideas}`
              });
            }

JSON Output Mode

When parsing API responses in CI scripts, use jq for reliable JSON extraction:

# Create an idea and capture the returned ID
IDEA_ID=$(curl -s -X POST "https://neuralrepo.com/api/v1/ideas" \
  -H "X-API-Key: $NEURALREPO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title": "Automated release tracking", "status": "captured"}' \
  | jq -r '.id')

echo "Created idea: $IDEA_ID"

# Use the ID in subsequent steps
curl -s -X PATCH "https://neuralrepo.com/api/v1/ideas/$IDEA_ID" \
  -H "X-API-Key: $NEURALREPO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "shipped"}'

Best Practices

• One key per pipeline. Create a separate API key for each CI environment so you can revoke individually.
• Use descriptive tags. Tag CI-created ideas with ci, the repository name, and the event type (e.g., release, deploy).
• Handle failures gracefully. Wrap NeuralRepo API calls in if: success() conditions so they only run after your primary workflow succeeds.
• Rate limits. The API allows 10,000 requests per day on Pro, counted per user across every key. Only X-API-Key and Bearer requests count — web sessions are exempt — so a CI pipeline shares its budget with the CLI and any MCP client on the same account. Exceeding it returns 429 with no Retry-After header; the counter resets at UTC midnight.
• Send X-API-Key, not Bearer, for nrp_ keys. The X-API-Key header is only inspected when the value starts with nrp_; MCP OAuth tokens go in Authorization: Bearer instead.

Caution

Check the response body, not just the status. Several NeuralRepo operations report failure inside a 2xx — bulk updates return a per-idea results array, and a key test returns {"ok": false} with a 200. A CI step that only checks the HTTP status will pass over a half-applied batch. See Errors.

Next Steps

API Overview Full API reference with authentication, pagination, and response formats.

Rate Limits How the daily counter works and which requests count against it.

CLI Installation Install the nrepo CLI for local and CI usage.

Migration Bulk-import existing ideas from Notion, Obsidian, or JSON.