Installation

Get TrueStory up and running in your Jira instance in just a few minutes.

Step 1: Install from Marketplace

1. Go to the Atlassian Marketplace
2. Click "Get it now" and select your Jira instance
3. Review and accept the permissions
4. Wait for the installation to complete

Step 2: Access TrueStory

Once installed, TrueStory appears in three places:

• Project Page - Access via Apps menu in your Jira project
• Issue Panel - View test cases on any issue
• Project Settings - Configure TrueStory for your project

Quick Start

Learn the basics of TrueStory and create your first test session.

Creating Test Cases

1. Open any Jira issue
2. Find the TrueStory panel on the right side
3. Click "Add Test" to create a new test case
4. Fill in the title, description, and severity
5. Click Save to link the test to the ticket

Using AI to Generate Tests

1. Configure your AI provider in Project Settings (Anthropic, OpenAI, DeepSeek, or Gemini)
2. Optionally create instruction templates in Coverage Settings. You can save up to 5, each for a different testing purpose
3. Open a ticket and click "Generate with AI" (if you have multiple templates, you'll pick which one to use)
4. Review the suggested test cases
5. Select the ones you want to keep and click Save

Running a Test Session

1. Go to the TrueStory project page (Apps > TrueStory)
2. Click "Create Session"
3. Select the tickets to test
4. Optionally assign a tester
5. Click "Start Testing" when ready
6. Mark each test as Pass, Warning, Fail, Skip, or Blocked
7. Click "Complete Session" when finished

Configuration

Configure TrueStory to match your team's workflow.

AI Provider Setup

TrueStory supports multiple AI providers for test generation:

• Anthropic (Claude) - Recommended for detailed test cases
• OpenAI (GPT-4) - Fast and reliable
• DeepSeek - Cost-effective alternative
• Gemini - Google's AI model

Enter your API key in Project Settings. Your key is stored securely in Forge storage and never leaves Atlassian's infrastructure.

Confluence Integration

1. Go to Project Settings > Confluence
2. Select an existing space or create a new one
3. Enable "Auto-sync reports" if you want automatic updates
4. Reports will be generated in the selected space

Webhook Configuration

For CI/CD integration, copy the webhook URL and API key from Project Settings:

CI/CD Integration

Integrate TrueStory into your CI/CD pipeline to block merges until QA approves.

GitHub Actions (Push-based)

The TrueStory GitHub App is connected. It automatically creates Check Runs when PRs are opened and updates them when QA completes. Your workflow just needs to deploy the preview.

GitHub Actions Workflow

name: Deploy Preview

on:
  pull_request:
    types: [opened, synchronize, reopened]
    branches: [main]

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

      - name: Deploy to Preview Environment
        # Your deployment step here (Firebase, Vercel, Netlify, etc.)
        # Example for Firebase:
        # uses: FirebaseExtended/action-hosting-deploy@v0
        # with:
        #   repoToken: ${{ secrets.GITHUB_TOKEN }}
        #   firebaseServiceAccount: ${{ secrets.FIREBASE_SERVICE_ACCOUNT }}
        #   projectId: your-project
        #   channelId: pr-${{ github.event.pull_request.number }}

# That's it! The TrueStory GitHub App automatically:
# 1. Detects PR events via webhook
# 2. Extracts ticket keys from PR title/branch (e.g., BUI-123)
# 3. Creates a "TrueStory QA Gate" Check Run
# 4. Creates a QA session with linked test cases
# 5. Updates the Check Run when QA completes
#
# Configure branch protection rules to require the
# "TrueStory QA Gate" check before merging.

GitLab CI/CD

stages:
  - deploy
  - qa

deploy-preview:
  stage: deploy
  script:
    - echo "Deploy your preview environment here"
    # Your deployment commands
  environment:
    name: preview/$CI_MERGE_REQUEST_IID
    url: https://preview-$CI_MERGE_REQUEST_IID.example.com
  only:
    - merge_requests

notify-truestory:
  stage: qa
  script:
    - |
      curl -s -X POST "$TRUESTORY_WEBHOOK_URL/gitlab" \
        -H "X-API-Key: $TRUESTORY_API_KEY" \
        -H "Content-Type: application/json" \
        -d "{
          \"event\": \"merge_request\",
          \"mr_iid\": $CI_MERGE_REQUEST_IID,
          \"mr_title\": \"$CI_MERGE_REQUEST_TITLE\",
          \"mr_url\": \"$CI_MERGE_REQUEST_PROJECT_URL/-/merge_requests/$CI_MERGE_REQUEST_IID\",
          \"source_branch\": \"$CI_MERGE_REQUEST_SOURCE_BRANCH_NAME\",
          \"target_branch\": \"$CI_MERGE_REQUEST_TARGET_BRANCH_NAME\",
          \"commit_sha\": \"$CI_COMMIT_SHA\",
          \"project_path\": \"$CI_PROJECT_PATH\"
        }"
  only:
    - merge_requests

# Required CI/CD Variables (Settings > CI/CD > Variables):
# - TRUESTORY_WEBHOOK_URL: Your TrueStory webhook URL
# - TRUESTORY_API_KEY: Your TrueStory API key

Bitbucket Pipelines

image: node:18

pipelines:
  pull-requests:
    '**':
      - step:
          name: Deploy Preview
          script:
            - echo "Deploy your preview environment here"
            # Your deployment commands

      - step:
          name: Notify TrueStory
          script:
            - |
              curl -s -X POST "$TRUESTORY_WEBHOOK_URL/bitbucket" \
                -H "X-API-Key: $TRUESTORY_API_KEY" \
                -H "Content-Type: application/json" \
                -d "{
                  \"event\": \"pullrequest:created\",
                  \"pr_id\": $BITBUCKET_PR_ID,
                  \"pr_title\": \"$BITBUCKET_PR_DESTINATION_BRANCH\",
                  \"source_branch\": \"$BITBUCKET_BRANCH\",
                  \"destination_branch\": \"$BITBUCKET_PR_DESTINATION_BRANCH\",
                  \"commit_sha\": \"$BITBUCKET_COMMIT\",
                  \"repo_slug\": \"$BITBUCKET_REPO_SLUG\",
                  \"workspace\": \"$BITBUCKET_WORKSPACE\"
                }"

# Required Repository Variables (Repository Settings > Pipelines > Repository variables):
# - TRUESTORY_WEBHOOK_URL: Your TrueStory webhook URL
# - TRUESTORY_API_KEY: Your TrueStory API key

Branch Protection (GitHub)

To block merges until QA approves:

1. Go to your GitHub repo → Settings → Branches
2. Add a branch protection rule for main
3. Enable "Require status checks to pass before merging"
4. Search for and add "TrueStory QA Gate" as a required check

How It Works

1. PR/MR is opened → GitHub App detects and creates a Check Run
2. TrueStory creates a QA session with linked test cases
3. QA team tests the preview in Jira and completes the session
4. TrueStory updates the Check Run to success/failure
5. Git provider unblocks merge when the Check passes

Confluence Reports

Automatically generate detailed test reports in Confluence.

Setting Up Reports

1. Go to Project Settings > Confluence
2. Select or create a Confluence space
3. Enable "Auto-sync reports" for automatic updates

Report Contents

Each session report includes:

• Session summary (pass/warning/fail counts)
• Test results with status and messages
• Links to Jira tickets
• Tester attribution
• Embedded screenshots and attachments
• Timestamps and duration

Overview Page

TrueStory also generates an overview page showing:

• Project coverage metrics
• Total test cases
• Session history
• Links to individual session reports

REST API

TrueStory provides a REST API for integrating with external tools and automating workflows.

Authentication

All API requests require authentication via Bearer token. Get your API key from TrueStory Settings in Jira.

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.true-story.tech/jira/{cloudId}/{projectKey}/sessions

Base URL

Sessions

List Sessions

Returns all sessions for a project. Filter with ?status=PENDING or ?status=COMPLETED.

Get Session

Returns session details including test cases and results.

Create Session

{
  "title": "Sprint 5 Regression",
  "description": "Optional description",
  "ticketKeys": ["PROJ-123", "PROJ-124"],
  "assignedToAccountId": "optional-jira-account-id"
}

Start Session

Transitions session from PENDING to IN_PROGRESS.

Submit Test Result

{
  "sessionTestCaseId": "stc-uuid",
  "status": "PASS",  // PASS, WARNING, FAIL, SKIPPED, BLOCKED
  "message": "Optional comment"
}

Complete Session

Finalizes session and calculates verdict (PASS, WARNING, or FAIL).

Test Cases

List Test Cases

Returns all test cases for a project.

Create Test Case

{
  "title": "User can login with valid credentials",
  "description": "Verify login flow works correctly",
  "severity": "HIGH",  // CRITICAL, HIGH, MEDIUM, LOW
  "steps": [
    { "step": 1, "action": "Navigate to /login", "expected": "Login form is displayed" },
    { "step": 2, "action": "Enter valid credentials", "expected": "Fields accept input" },
    { "step": 3, "action": "Click Submit", "expected": "User is redirected to dashboard" }
  ]
}

Get Tests for Ticket

Returns all test cases linked to a specific Jira ticket.

Link Test to Ticket

{
  "testCaseId": "tc-uuid"
}

Coverage

Get Coverage Stats

Returns test coverage distribution for the project.

Webhooks

GitHub PR Webhook

Receives GitHub PR events and creates QA sessions automatically. See CI/CD Integration for setup.

Check Session Status (for CI/CD)

Returns session status for CI/CD polling. Response includes status and verdict.

Response Codes

Frequently Asked Questions