Integrations

Integrations allow you to securely store and manage credentials for external services like Jira and GitHub. These credentials are encrypted at rest using AES-256 and can be scoped to specific projects or made globally available.

Key Concepts

What is an Integration?

An integration is a secure credential store that connects sfp server to external services. For example:

Jira integration: Stores your Jira API credentials so sfp can fetch work items, link commits to issues, and track deployment status
GitHub integration: Stores GitHub tokens for repository access, PR comments, and status checks

Global vs Project-Scoped Integrations

Scope	Use Case	Example
Global (`isGlobal: true`)	Single set of credentials shared across all projects	Company-wide Jira instance
Project-scoped (`projects: [...]`)	Credentials specific to certain repositories	Per-repo GitHub App tokens

When to use global integrations:

You have one Jira instance for all projects
You want a fallback credential when no project-specific one exists

When to use project-scoped integrations:

Different teams use different Jira projects
You need separate GitHub tokens per repository
Security requires credential isolation between projects

Authentication Types

Type	Provider	Use Case
`pat`	GitHub	Personal Access Token for API access
`oauth`	GitHub, Jira	OAuth flow for user-delegated access
`app`	GitHub	GitHub App installation token
`basic_auth`	Jira	Email + API token (recommended for Jira Cloud)

API Reference

Create Integration

POST /sfp/api/integrations

Request Body:

Field	Type	Required	Description
`provider`	string	Yes	Service provider: `github` or `jira`
`authType`	string	Yes	Authentication type: `pat`, `oauth`, `app`, or `basic_auth`
`credentials`	object	Yes	Provider-specific credentials (see examples below)
`isGlobal`	boolean	No	Set `true` for global integration
`projects`	string[]	No	Project identifiers (required if not global)
`config`	object	No	Provider-specific configuration

Example: Global Jira Integration

curl -X POST https://your-server/sfp/api/integrations \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "jira",
    "authType": "basic_auth",
    "credentials": {
      "base_url": "https://your-company.atlassian.net",
      "username": "your-email@company.com",
      "api_token": "your-jira-api-token"
    },
    "isGlobal": true
  }'

Example: Project-Scoped GitHub Integration

curl -X POST https://your-server/sfp/api/integrations \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "github",
    "authType": "pat",
    "credentials": {
      "token": "ghp_xxxxxxxxxxxx"
    },
    "projects": ["your-org/sf-core", "your-org/sf-sales"]
  }'

Get Credentials

Retrieve stored credentials for use in automation. All access is audited.

GET /sfp/api/integrations/credentials?provider={provider}&project={project}

Query Parameters:

Parameter	Required	Description
`provider`	No	Filter by provider (`github`, `jira`)
`project`	No	Filter by project identifier

Example:

# Get Jira credentials for a specific project
curl "https://your-server/sfp/api/integrations/credentials?provider=jira&project=your-org/sf-core" \
  -H "Authorization: Bearer $TOKEN"

Response:

[
  {
    "integration_id": "uuid-here",
    "provider": "jira",
    "auth_type": "basic_auth",
    "credentials": {
      "base_url": "https://your-company.atlassian.net",
      "username": "your-email@company.com",
      "api_token": "your-jira-api-token"
    }
  }
]

Complete Workflow Example

Here's a typical setup workflow for a new team:

1. Register Your Project

sfp server project create \
  --identifier "acme-corp/salesforce-main" \
  --remote-url "https://github.com/acme-corp/salesforce-main"

2. Create a Global Jira Integration

Since most teams share a single Jira instance:

curl -X POST https://your-server/sfp/api/integrations \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "jira",
    "authType": "basic_auth",
    "credentials": {
      "base_url": "https://acme.atlassian.net",
      "username": "sfp-service@acme.com",
      "api_token": "ATATT3xFfGF0..."
    },
    "isGlobal": true
  }'

3. Create Project-Scoped GitHub Integration

For repository-specific access:

curl -X POST https://your-server/sfp/api/integrations \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "github",
    "authType": "pat",
    "credentials": {
      "token": "ghp_xxxx"
    },
    "projects": ["acme-corp/salesforce-main"]
  }'

4. Use in Your Pipeline

Once configured, sfp commands automatically use the stored credentials:

# Work items are fetched using stored Jira credentials
sfp work-items list --project "acme-corp/salesforce-main"

Security Considerations

Encryption: All credentials are encrypted at rest using AES-256 via Supabase pgcrypto
Audit Logging: Every credential access is logged with actor information
Least Privilege: Use project-scoped integrations when possible to limit blast radius
Token Rotation: Regularly rotate API tokens and update integrations accordingly

Troubleshooting

"Either isGlobal or projects must be specified"

You must specify either isGlobal: true OR provide a projects array. You cannot omit both.

"Project 'xyz' not found"

The project identifier must match an existing registered project. List projects first:

sfp server project list

"No integration found for project=xyz"

Either no integration exists for that project, or the integration is not scoped to include it. Check if a global integration exists or create a project-scoped one.

On this page