What API Tokens Do You Need Before Starting?
Before opening FlowSquad's integration settings, generate the following tokens in their respective tools. Having all 3 ready before starting will get you through the setup in a single session.
Required API tokens — generate these first
Navigate to: GitHub Settings → Developer settings → Personal access tokens → Tokens (classic) → Generate new token
Token format: ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx (40 chars)
Navigate to: id.atlassian.com → Security → API tokens → Create API token
Used with your Atlassian account email as the username
Token format: ATATxxxxxxxxxxxxxxxxxxxxxxxx (Base64, ~24 chars)
You only need one Atlassian API token for both Jira and Confluence integrations
How Do You Connect GitHub (or GitLab/Bitbucket/Azure DevOps)?
FlowSquad's GitHub integration supports GitHub.com and GitHub Enterprise. It also supports GitLab (cloud and self-hosted), Bitbucket Cloud, Bitbucket Data Center, and Azure DevOps Repos.
GitHub connection steps
- Open FlowSquad → Settings → Integrations → Source Control
- Click Add GitHub Connection. Select Personal Access Token (for individual repos) or GitHub App (for org-wide access — recommended for teams).
- Paste your PAT in the Token field. Enter your GitHub username in the Username field.
- Enter the repository URL. Format: https://github.com/{owner}/{repo} or for Enterprise: https://github.yourdomain.com/{owner}/{repo}
- Click Test Connection. You should see: "Connection successful — 1 repository accessible."
- Click Save. The repository now appears in your FlowSquad project's source control list.
If you want PR-triggered quality scans, enable the webhook. FlowSquad generates a webhook URL (format: https://app.flowsquad.ai/api/webhooks/github/{project-id}) that you add to your GitHub repository's Webhook settings with a shared secret.
How Do You Connect Jira?
FlowSquad's Jira integration supports Jira Cloud and Jira Data Center (version 8.x and above).
- Open FlowSquad → Settings → Integrations → Jira
- Enter your Jira Base URL. For Jira Cloud: https://your-org.atlassian.net. For Jira Data Center: https://jira.yourdomain.com
- Enter your Atlassian Account Email (the email you use to log in to Atlassian)
- Paste your Atlassian API Token in the Token field
- Enter your Jira Project Key. This is the 2–6 character prefix of your issue numbers. Example: if your issues are PET-123, your project key is PET
- Click Test Connection. FlowSquad calls GET /rest/api/3/myself to verify authentication, then GET /rest/api/3/project/{key} to verify project access.
- Configure Issue Type Mappings: map FlowSquad's Epic → Jira Epic, Story → Story, Task → Sub-task (or Task — your preference)
- Click Save Integration
How Do You Connect Confluence?
FlowSquad's Confluence integration exports generated HLD and LLD documents as Confluence pages. Supported: Confluence Cloud and Confluence Data Center (7.x+).
- Open FlowSquad → Settings → Integrations → Confluence
- Enter your Confluence Base URL. For Confluence Cloud: https://your-org.atlassian.net/wiki. For Data Center: https://confluence.yourdomain.com
- Enter the same Atlassian Account Email and API Token as Jira (same credential)
- Enter the Space Key where FlowSquad should create pages. Navigate to your Confluence space and find it in the URL: https://your-org.atlassian.net/wiki/spaces/{SPACEKEY}/
- Set the Parent Page (optional). If you want FlowSquad pages to be nested under a specific page (e.g., "Technical Design Docs"), enter its page ID. Find the page ID by clicking ··· menu → Page Information → the ID is in the URL.
- Click Test Connection. FlowSquad verifies space access and write permissions.
- Click Save Integration
How Do You Test That Auto-Export Works?
With all 3 integrations connected, run this end-to-end test to confirm everything works:
- Open any FlowSquad project with a connected repository
- Click Generate Work Breakdown and enter: "Add user password reset via email"
- Wait for generation to complete (~60–90 seconds)
- Click Export to Jira → Select your project key → Click Create Issues
- Open your Jira project — you should see new epics and stories created with the prefix [FlowSquad] in the summary
- Click Export Design to Confluence → Select your space → Click Publish Page
- Open your Confluence space — the new page should appear under your parent page with the HLD content
Troubleshooting: 3 Common Errors and Their Fixes
Jira Test Connection fails with 401 Unauthorized
Message: {"errorMessages":["You do not have permission to access this resource"]}
This is almost always a wrong email/token combination. Confirm you are using your Atlassian account email (the one at id.atlassian.com), not a display name or username. Regenerate the API token if it was created more than 12 months ago (Atlassian tokens do not expire but can be revoked). Also check that you have the Browse Projects and Create Issues permissions in the target Jira project — these are required by FlowSquad.
GitHub webhook test returns 403 Forbidden
Message in FlowSquad logs: Webhook delivery failed: 403 — signature mismatch
The webhook shared secret in GitHub does not match the one generated by FlowSquad. In GitHub → Repository Settings → Webhooks → your FlowSquad webhook → Edit: update the Secret field with the exact secret string shown in FlowSquad's integration settings (copy it using the copy button — avoid manual retyping which introduces whitespace). If the secret was auto-generated, you can regenerate it in FlowSquad and re-paste to GitHub.
Confluence export fails with "Page already exists"
Message: {"message":"title already exists in space"}
FlowSquad tried to create a page with a title that already exists in your Confluence space. Two options: (1) Enable Update on conflict in FlowSquad's Confluence settings — this will update the existing page instead of failing. (2) Enable the Timestamp in title option to append a date suffix to all generated page titles, ensuring uniqueness. Both options are in FlowSquad → Settings → Integrations → Confluence → Advanced Settings.