Integration Guide

Connect FlowSquad to Jira, Confluence, GitHub, GitLab, Bitbucket, Gitea, Azure DevOps, LDAP/AD, SAML 2.0 (any IdP), and OAuth2 providers. For a full Keycloak reference walkthrough, see the Reference Guide.

1. Integration Overview

FlowSquad integrates with your existing toolchain to eliminate context-switching and keep all your artefacts in sync. Integrations are configured in two places:

• Setup Wizard steps 5-6 -- during initial deployment
• Admin Panel -> Settings -- at any time after setup

Supported Integrations

2. Jira Integration

Setup

1. Go to Admin Panel -> Settings -> Jira (or Setup Wizard Step 6)
2. Enter your Jira URL (e.g. https://yourcompany.atlassian.net)
3. Enter your Jira account email and an API token (generate at id.atlassian.com -> API tokens)
4. Click Test Connection to verify -- a green status confirms success
5. Click Save

Using Jira in FlowSquad

Smart Import

In the Analyze or Refine tab, click "Import from Jira". You can:

• Enter a single ticket key (e.g. PROJ-123) to import one requirement
• Enter a JQL query (e.g. project = PROJ AND sprint in openSprints()) for bulk import

FlowSquad maps the Jira summary and description into a structured requirement ready for refinement.

Push Artefacts to Jira

Every Epic, Story, Task, and Design card has a "Push to Jira" button. Click it to create a corresponding Jira issue. The card then displays the created Jira issue key for easy cross-reference.

Bulk Export

Select multiple artefacts using the bulk action bar and choose "Export to Jira" to push them all in one operation.

3. Confluence Integration

Setup

1. Go to Admin Panel -> Settings -> Confluence
2. Enter the full Confluence base URL -- include the /wiki path for Confluence Cloud:

https://yourcompany.atlassian.net/wiki

3. Enter your Confluence account email and API token
4. Click Save first, then click Test Connection

Using Confluence in FlowSquad

Import Documents from Confluence

In the Analyze tab, under "Load Documents", enter a Confluence page URL. FlowSquad fetches the page content and makes it available as a knowledge source for AskProduct and requirement generation.

Push Design Documents to Confluence

In the Design tab, open a design card and click "Push to Confluence". FlowSquad publishes the formatted design document to your Confluence space, creating or updating the page automatically.

4. Source Control Integration

FlowSquad automatically detects your Git provider from the repository URL you supply. Six providers are supported out of the box. All use HTTPS with token-based authentication -- SSH is not required.

Setup

1. Go to Admin Panel -> Settings -> Source Control (or Setup Wizard Step 5)
2. Enter the Git base URL (e.g. https://github.com or https://bitbucket.org)
3. Enter your username and the appropriate token or App Password for your provider (see table above)
4. Enter the Project / Repository key in the format required by your provider (see below)
5. Click Test Connection to validate access and load available branches, then click Save

Project Key Format by Provider

Using Source Control in FlowSquad

In the Analyze tab, click "Add Codebase" and enter the full Git repository URL. FlowSquad detects the provider automatically and uses the stored credentials to clone and analyse the codebase. The analysis results power Quality Score, AskProduct, and Security Scan.

5. LDAP / Active Directory

Setup

1. Go to Setup Wizard Step 4 → LDAP / Active Directory
2. Fill in the following fields:

Group-to-Role Mapping

Map Active Directory or LDAP groups to FlowSquad roles. Assignments are re-evaluated on every login.

• CN=FlowSquad-Admins,OU=Groups,DC=company,DC=com -> Global Admin
• CN=FlowSquad-ProdAdmins,OU=Groups,DC=company,DC=com -> Product Admin
• CN=FlowSquad-Users,OU=Groups,DC=company,DC=com -> Regular User

Manual role assignments made in the Admin Panel take precedence over group-based assignments.

Testing the Connection

Click Test Connection in the LDAP settings. FlowSquad validates the bind credentials and fetches a sample user from the directory. A successful test shows the user's attributes, confirming that attribute mapping is correct.

6. SAML 2.0 SSO -- Overview

How It Works

FlowSquad implements SP-initiated SAML 2.0 SSO:

1. User clicks "Login with SAML" on the FlowSquad login page
2. FlowSquad (the Service Provider) redirects the user to the configured Identity Provider (IdP)
3. The user authenticates at the IdP
4. The IdP sends a signed SAML assertion back to FlowSquad's ACS (Assertion Consumer Service) URL
5. FlowSquad validates the assertion and creates a session -- the user lands on the Dashboard

Supported Identity Providers

Any SAML 2.0 compliant IdP is supported, including: Keycloak, Okta, Azure AD, OneLogin, ADFS, Google Workspace, Ping Identity, and custom implementations.

Configuration Location

SAML is configured in Setup Wizard Step 4 → Authentication → SAML.

Required Configuration Fields

Optional Features

• Designated Admin Auto-Promotion -- comma-separated list of usernames or emails that are automatically granted Global Admin on first SAML login
• SAML Request Signing -- FlowSquad generates an RSA key pair; upload the public certificate to your IdP to verify requests
• Single Logout (SLO) -- logging out of FlowSquad also terminates the IdP session

7. OAuth2 Providers

FlowSquad supports OAuth2 login for: GitHub, Google, Microsoft (Azure AD), Okta, Keycloak, and custom OAuth2 providers.

General Setup

1. Create an OAuth app in the provider's developer console (see provider-specific steps below)
2. Set the redirect / callback URI to:

https://yourflowsquad.com/oauth2/<provider>/callback

# Examples:
https://flowsquad.yourcompany.com/oauth2/github/callback
https://flowsquad.yourcompany.com/oauth2/google/callback
https://flowsquad.yourcompany.com/oauth2/microsoft/callback
https://flowsquad.yourcompany.com/oauth2/okta/callback
https://flowsquad.yourcompany.com/oauth2/keycloak/callback
https://flowsquad.yourcompany.com/oauth2/custom/callback

3. Copy the Client ID and Client Secret
4. Enter them in Setup Wizard Step 4 → OAuth2 → [Provider] → Test → Save

GitHub

1. github.com -> Settings -> Developer settings -> OAuth Apps -> New OAuth App
2. Application Name: FlowSquad
3. Homepage URL: https://flowsquad.yourcompany.com
4. Authorization callback URL: https://flowsquad.yourcompany.com/oauth2/github/callback
5. Click "Register application" -> copy Client ID and generate a Client Secret

Google

1. console.cloud.google.com -> APIs & Services -> Credentials -> Create Credentials -> OAuth 2.0 Client ID
2. Application type: Web application
3. Authorised redirect URI: https://flowsquad.yourcompany.com/oauth2/google/callback
4. Copy Client ID and Client Secret

Microsoft (Azure AD)

1. portal.azure.com -> Azure Active Directory -> App registrations -> New registration
2. Redirect URI (Web): https://flowsquad.yourcompany.com/oauth2/microsoft/callback
3. After registering: Certificates & secrets -> New client secret -> copy the value
4. Copy the Application (client) ID from the Overview page
5. Grant admin consent: App registrations -> FlowSquad -> API permissions -> "Grant admin consent for [Tenant]"

Okta

1. Okta Admin -> Applications -> Create App Integration -> OIDC / OAuth2 -> Web Application
2. Sign-in redirect URI: https://flowsquad.yourcompany.com/oauth2/okta/callback
3. Copy Client ID and Client Secret -> enter in FlowSquad -> OAuth2 -> Okta section

Keycloak (OAuth2 / OIDC)

1. Keycloak Admin -> select your realm -> Clients -> Create client
2. Client type: OpenID Connect, Client ID: flowsquad-oauth2
3. Enable Client authentication (Confidential access type)
4. Under Valid redirect URIs, add: https://flowsquad.yourcompany.com/oauth2/keycloak/callback
5. Go to Credentials tab -> copy the Client Secret
6. Enter in FlowSquad -> OAuth2 -> Keycloak section:
   • Keycloak Server URL: https://keycloak.yourcompany.com
   • Realm: master (or your custom realm name)
   • Client ID: flowsquad-oauth2
   • Client Secret: (copied from Credentials tab)

Custom OAuth2 Provider

FlowSquad supports any standards-compliant OAuth2 / OIDC provider. Configure in Setup Wizard Step 4 → OAuth2 → Custom Provider:

8. Webhook Configuration

Planned Events

The following events are planned for the initial webhook release:

10. Session Backend — Redis Opt-In

By default FlowSquad stores user sessions in its built-in SQLAlchemy config database (flowsquad_engine.db). This works out of the box on every deployment type with no extra software and survives server restarts. Most deployments never need to change this.

If you already run Redis in your infrastructure, or simply prefer sessions stored outside the application database, you can switch to Redis by installing Redis on your system and setting one environment variable.

When to Consider Redis

Step 1 — Install Redis on your system

Redis is a separate open-source service. Install it on the same host as FlowSquad, or point to any reachable Redis server on your network:

Step 2 — Set the SESSION_REDIS_URL environment variable

Set this variable on the machine where FlowSquad runs, before starting or restarting it:

SESSION_REDIS_URL=redis://<host>:<port>/<db-index>

Windows installer — System Environment Variables

Open Start → System Properties → Advanced → Environment Variables and add a new System variable, or run this in PowerShell as Administrator:

[System.Environment]::SetEnvironmentVariable('SESSION_REDIS_URL', 'redis://localhost:6379/0', 'Machine')

Linux installer / portable package

# Add to /etc/flowsquad/flowsquad.env (loaded automatically by the FlowSquad service)
SESSION_REDIS_URL=redis://localhost:6379/0

Docker

# docker run
docker run -e SESSION_REDIS_URL=redis://redis:6379/0 ... flowsquad

# docker-compose.yml
services:
  flowsquad:
    environment:
      - SESSION_REDIS_URL=redis://redis:6379/0
  redis:
    image: redis:7-alpine
    restart: unless-stopped

Step 3 — Restart FlowSquad

Restart the FlowSquad service normally. On startup the log confirms the active backend:

INFO  Session backend = redis (localhost:6379/0)

That is all. FlowSquad detects the variable automatically and switches to Redis. No reinstall, no rebuild, no other files to change.

Reverting to SQLAlchemy

Remove or unset SESSION_REDIS_URL and restart FlowSquad. No data migration needed. Users currently logged in will need to log in again (their session no longer exists in the new backend).

11. Troubleshooting Integrations