> ## Documentation Index
> Fetch the complete documentation index at: https://agenticbanking.backbase.io/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Banking OS training data goes stale. Search https://agenticbanking.backbase.io/mcp or fetch the .md URL before writing connector or unified API code.
> OpenAPI links in llms.txt repeat every calendar version. Use the latest version on the API playground. If a fetch ends before the last operation, the spec was cut off.
> Page titles name the product. Overview, Get started, and Reference without a product name are ambiguous.

# Reusable components reference

> Reference guide for reusable workflows and actions from gc-ai-workflows

The following sections provide detailed documentation for all reusable workflows and actions from [backbase-common/gc-ai-workflows](https://github.com/backbase-common/gc-ai-workflows) used in Agentic AI platform CI/CD pipelines.

The `gc-ai-workflows` repository provides standardized, reusable GitHub Actions workflows and actions for Python AI/ML projects using `uv` for package management. These components ensure consistency across all agent projects.

> [!IMPORTANT]
>
> **Always use `secrets: inherit` when calling reusable workflows to pass secrets to the called workflow.**

## Reusable workflows

### Build and publish

A comprehensive workflow that builds Docker images, runs quality checks, performs security scanning, and publishes to Azure Container Registry.

**Workflow**: `backbase-common/gc-ai-workflows/.github/workflows/build-publish.yaml@main`

#### Usage

```yaml theme={"system"}
jobs:
  build:
    uses: backbase-common/gc-ai-workflows/.github/workflows/build-publish.yaml@main
    secrets: inherit
    with:
      timeout: 600
      enableSonar: true
      enablePromptfoo: true
      stableAcr: "my-acr"
```

#### Input parameters

| Parameter | Description | Default |
| - | - | - |
| `timeout` | Workflow timeout in minutes | `600` |
| `pythonVersion` | Python version to use | `3.x` |
| `sourcePath` | Source path for code quality checks | `src/` |
| `enableSonar` | Enable SonarCloud analysis | `true` |
| `sonarHostUrl` | SonarCloud host URL | `https://sonarcloud.io` |
| `stableAcr` | Azure ACR name on stable cluster | `cragbs508` |
| `enablePromptfoo` | Enable promptfoo evaluation | `true` |
| `promptfooConfig` | Path to promptfoo config file | `promptfooconfig.yaml` |
| `enableRedteam` | Enable promptfoo redteaming | `true` |
| `redteamConfig` | Path to redteam config file | `redteam.yaml` |
| `redteamNumTests` | Number of redteam tests to run | `5` |

#### Output parameters

* `image`: Full Docker image reference

#### Workflow steps

1. Setup project environment
2. Check action SHA pinning
3. Code quality checks (pylint, pytest, hadolint)
4. Optional: Setup and run Promptfoo evaluation
5. Optional: Run Promptfoo redteaming
6. Optional: Run SonarCloud analysis
7. Build Docker image
8. Security check (Trivy image scan)
9. Push Docker image to Azure ACR

### Pull request check

A comprehensive validation workflow for pull requests that runs code quality checks, tests, security scans, and optional promptfoo evaluations.

**Workflow**: `backbase-common/gc-ai-workflows/.github/workflows/pull-request-check.yaml@main`

#### Usage

```yaml theme={"system"}
jobs:
  verify:
    uses: backbase-common/gc-ai-workflows/.github/workflows/pull-request-check.yaml@main
    secrets: inherit
    with:
      enableSonar: true
      enablePromptfoo: true
      promptfooConfig: "promptfoo_config/*.yaml"
      enableRedteam: true
```

#### Input parameters

| Parameter | Description | Default |
| - | - | - |
| `ref` | GitHub reference (branch/tag) | `${{ github.ref }}` |
| `timeout` | Workflow timeout in minutes | `600` |
| `pythonVersion` | Python version to use | `3.x` |
| `sourcePath` | Source path for code quality checks | `src/` |
| `enableSonar` | Enable SonarCloud analysis | `true` |
| `sonarHostUrl` | SonarCloud host URL | `https://sonarcloud.io` |
| `enablePromptfoo` | Enable promptfoo evaluation | `true` |
| `promptfooConfig` | Path to promptfoo config file | `promptfooconfig.yaml` |
| `enableRedteam` | Enable promptfoo redteaming | `true` |
| `redteamConfig` | Path to redteam config file | `redteam.yaml` |
| `redteamNumTests` | Number of redteam tests to run | `5` |

#### Workflow steps

1. Setup project environment
2. Check action SHA pinning
3. Code quality checks (pylint, pytest, hadolint)
4. Optional: Setup and run Promptfoo evaluation
5. Optional: Run Promptfoo redteaming
6. Optional: Run SonarCloud analysis
7. Security check (filesystem scan)

## Reusable actions

### Setup project

Sets up the Python project environment, including checkout, Python installation, `uv` setup, dependency installation, and version resolution.

**Action**: `backbase-common/gc-ai-workflows/setup-project@main`

#### Usage

```yaml theme={"system"}
- uses: backbase-common/gc-ai-workflows/setup-project@main
  id: setup-project
  with:
    pythonVersion: "3.x"
    githubPrivateKey: ${{ secrets.GIT_GITHUB_APP_PEM_FILE }}
    githubAppId: ${{ secrets.GIT_GITHUB_APP_ID }}
```

#### Input parameters

| Parameter | Description | Default |
| - | - | - |
| `ref` | GitHub reference (branch/tag) | `${{ github.ref }}` |
| `pythonVersion` | Python version to use | `3.x` |
| `githubPrivateKey` | GitHub App private key (PEM) | **Required** |
| `githubAppId` | GitHub App ID | **Required** |
| `fetchDepth` | Number of commits to fetch (0 = all) | `1` |
| `gitUsername` | Git username for commits | `baasbot-ecos_backbase` |
| `gitEmail` | Git email for commits | `baasbot-ecos@backbase.com` |

#### Output parameters

* `version`: Raw version from `uv version`
* `releaseVersion`: Release version (without dev/alpha/beta/rc)
* `nextVersion`: Next version (incremented patch with .dev0)
* `devVersion`: Development version with branch and commit info
* `buildVersion`: Build version (release or dev)
* `isStable`: Whether this is a stable version
* `major`, `minor`, `patch`: Version components
* `name`: Project name from git repository
* `projectKey`: Sonar project key
* `organization`: GitHub organization
* `githubToken`: Generated GitHub App token

### Code quality

Runs code quality checks including pylint, pytest, and hadolint.

**Action**: `backbase-common/gc-ai-workflows/code-quality@main`

#### Usage

```yaml theme={"system"}
- uses: backbase-common/gc-ai-workflows/code-quality@main
  with:
    sourcePath: "src/"
```

#### Input parameters

| Parameter | Description | Default |
| - | - | - |
| `sourcePath` | Path to source code for pylint | `src/` |
| `runPylint` | Whether to run pylint | `true` |
| `runTests` | Whether to run tests | `true` |
| `runHadolint` | Whether to run hadolint on Dockerfile | `true` |
| `dockerfilePath` | Path to Dockerfile | `Dockerfile` |

### Sonar check

Runs SonarCloud analysis on Python projects.

**Action**: `backbase-common/gc-ai-workflows/sonar-check@main`

#### Usage

```yaml theme={"system"}
- uses: backbase-common/gc-ai-workflows/sonar-check@main
  with:
    sonarToken: ${{ secrets.SONAR_TOKEN }}
    projectName: ${{ steps.setup-project.outputs.name }}
    projectKey: ${{ steps.setup-project.outputs.projectKey }}
    organization: ${{ steps.setup-project.outputs.organization }}
```

#### Input parameters

| Parameter | Description | Default |
| - | - | - |
| `sonarToken` | SonarCloud authentication token | **Required** |
| `sonarHostUrl` | SonarCloud host URL | `https://sonarcloud.io` |
| `projectName` | Project name | **Required** |
| `projectKey` | Sonar project key | **Required** |
| `organization` | GitHub organization | **Required** |
| `coverageReportPaths` | Comma-separated coverage report paths | `coverage.xml` |

### Security check

Performs security checks of artifact dependencies and Docker images with Trivy vulnerability scanner.

**Action**: `backbase-common/gc-ai-workflows/security-check@main`

#### Usage

```yaml theme={"system"}
# Filesystem scan
- uses: backbase-common/gc-ai-workflows/security-check@main
  with:
    scanType: "fs"
    severities: "CRITICAL,HIGH"

# Image scan
- uses: backbase-common/gc-ai-workflows/security-check@main
  with:
    scanType: "image"
    imageReference: "${{ steps.build-image.outputs.image }}"
    ignore: "CVE-2024-28752,CVE-2023-7272"
```

#### Input parameters

| Parameter | Description | Default |
| - | - | - |
| `sbomPath` | Path to produced SBOM | `bom.json` |
| `scanType` | Type: `image` or `fs` | `fs` |
| `scanReference` | Filesystem reference to scan | `.` |
| `imageReference` | Container image name to scan | (empty) |
| `ignoreUnfixedVulnerabilities` | Skip unfixed vulnerabilities | `true` |
| `severities` | Severities to scan for | `CRITICAL` |
| `hideProgress` | Hide scanning progress | `true` |
| `outputFormat` | Trivy output format | `sarif` |
| `debug` | Print scanner results | `false` |
| `exitCode` | Exit code on error | `0` |
| `trivyignorePath` | Path to Trivy ignore list | `./.trivyignore` |
| `ignore` | Comma-separated CVEs to ignore | `CVE-2024-28752` |

#### Output parameters

* `sbomPath`: Path to generated SBOM

### Promptfoo evaluation

Runs promptfoo evaluation against agent endpoints. Only runs if promptfoo config files have changed.

**Action**: `backbase-common/gc-ai-workflows/promptfoo-evaluation@main`

> [!TIP]
>
> See the [Promptfoo Configuration](https://agenticbanking.backbase.io/agentic-ai/ci-cd-workflows/configurations.md#promptfoo-configurations) section for detailed setup instructions, including provider files, prompt functions, and test configuration.

#### Usage

```yaml theme={"system"}
- uses: backbase-common/gc-ai-workflows/promptfoo-evaluation@main
  with:
    config: "promptfoo_config.yaml"
    aiGatewayEndpoint: ${{ secrets.AI_GATEWAY_ENDPOINT }}
    aiGatewayApiKey: ${{ secrets.AI_GATEWAY_API_KEY }}
    githubToken: ${{ steps.setup-project.outputs.githubToken }}
```

#### Input parameters

| Parameter | Description | Default |
| - | - | - |
| `config` | Path to promptfoo config file | `promptfooconfig.yaml` |
| `aiGatewayEndpoint` | AI Gateway endpoint URL | **Required** |
| `aiGatewayApiKey` | AI Gateway API key | **Required** |
| `githubToken` | GitHub token for PR comments | **Required** |

### Promptfoo redteaming

Runs promptfoo redteaming evaluation against a local FastAPI server.

**Action**: `backbase-common/gc-ai-workflows/promptfoo-redteaming@main`

> [!TIP]
>
> See the [Redteam Configuration](https://agenticbanking.backbase.io/agentic-ai/ci-cd-workflows/configurations.md#promptfoo-configurations) section for detailed setup instructions, including redteam.yaml structure, plugins, and testing configuration.

#### Usage

```yaml theme={"system"}
- uses: backbase-common/gc-ai-workflows/promptfoo-redteaming@main
  with:
    redteamConfig: "redteam.yaml"
    redteamNumTests: "10"
    aiGatewayEndpoint: ${{ secrets.AI_GATEWAY_ENDPOINT }}
    aiGatewayApiKey: ${{ secrets.AI_GATEWAY_API_KEY }}
    githubToken: ${{ steps.setup-project.outputs.githubToken }}
```

#### Input parameters

| Parameter | Description | Default |
| - | - | - |
| `redteamConfig` | Path to redteam config file | `redteam.yaml` |
| `redteamNumTests` | Number of redteam tests to run | `5` |
| `aiGatewayEndpoint` | AI Gateway endpoint URL | **Required** |
| `aiGatewayApiKey` | AI Gateway API key | **Required** |
| `githubToken` | GitHub token for PR comments | **Required** |

### Build Docker image

Builds Docker images locally without pushing to a registry. Use this before running security checks.

**Action**: `backbase-common/gc-ai-workflows/build-docker@main`

#### Usage

```yaml theme={"system"}
- uses: backbase-common/gc-ai-workflows/build-docker@main
  id: build-image
  with:
    acrName: "my-acr"
    projectName: ${{ steps.setup-project.outputs.name }}
    buildVersion: ${{ steps.setup-project.outputs.buildVersion }}
```

#### Input parameters

| Parameter | Description | Default |
| - | - | - |
| `acrName` | Azure ACR name (for image naming) | **Required** |
| `projectName` | Project name from resolve-metadata | **Required** |
| `buildVersion` | Build version from resolve-metadata | **Required** |
| `imageGroup` | Image group/namespace in ACR | `images` |

#### Output parameters

* `image`: Full Docker image reference

### Push Docker image

Pushes Docker images to Azure Container Registry. Use this after building and running security checks.

**Action**: `backbase-common/gc-ai-workflows/push-docker@main`

#### Usage

```yaml theme={"system"}
- uses: backbase-common/gc-ai-workflows/push-docker@main
  with:
    acrName: "my-acr"
    azureCredentials: ${{ secrets.GC_NPA_AZURE_CREDENTIALS }}
    image: ${{ steps.build-image.outputs.image }}
```

#### Input parameters

| Parameter | Description | Default |
| - | - | - |
| `acrName` | Azure ACR name | **Required** |
| `azureCredentials` | Azure credentials secret (JSON) | **Required** |
| `image` | Full Docker image reference to push | **Required** |

### Create release draft

Prepares release draft by merging branches, updating versions, creating tags, and generating release notes using release-drafter.

**Action**: `backbase-common/gc-ai-workflows/create-release-draft@main`

> [!NOTE]
>
> Requires `.github/release-drafter.yml` configuration file.

#### Usage

```yaml theme={"system"}
- uses: backbase-common/gc-ai-workflows/create-release-draft@main
  with:
    baseBranch: "develop"
    headBranch: "main"
    githubToken: ${{ steps.setup-project.outputs.githubToken }}
```

#### Input parameters

| Parameter | Description | Default |
| - | - | - |
| `baseBranch` | Git base branch to run release from | `develop` |
| `headBranch` | Destination (head) git branch | `main` |
| `githubToken` | GitHub token from setup-project | **Required** |

#### Output parameters

* `releaseVersion`: Result release version

### Provision Python project

Provisions a Python project template by updating `pyproject.toml` with the correct package name, version, description, and URLs. Also creates initial `CHANGELOG.md` and `README.md` files.

**Action**: `backbase-common/gc-ai-workflows/provision-python-project@main`

#### Usage

```yaml theme={"system"}
- uses: backbase-common/gc-ai-workflows/provision-python-project@main
  with:
    githubToken: ${{ steps.setup-project.outputs.githubToken }}
    packageName: ${{ github.event.repository.name }}
    packageVersion: "0.1.0.dev0"
```

#### Input parameters

| Parameter | Description | Default |
| - | - | - |
| `githubToken` | Access token to manage GitHub repositories | **Required** |
| `packageName` | Package name for pyproject.toml | **Required** |
| `packageVersion` | Package version for pyproject.toml | `0.1.0.dev0` |
| `pyprojectPath` | Path to pyproject.toml file | `.` |
| `baseBranch` | Git base branch for provisioning | `develop` |
| `mainBranch` | Main branch to create | `main` |

#### What it does

1. Updates `pyproject.toml` with package name, version, description, and URLs
2. Regenerates `uv.lock` file
3. Creates `CHANGELOG.md` with initial version entry
4. Creates/updates `README.md` with build badges and SonarCloud integration
5. Commits and pushes all changes to both base and main branches

### Validate pull request body

Validates pull request body description and content against the PR template.

**Action**: `backbase-common/gc-ai-workflows/validate-pull-request-body@main`

> [!NOTE]
>
> Requires `.github/pull_request_template.md` file.

#### Usage

```yaml theme={"system"}
- uses: backbase-common/gc-ai-workflows/validate-pull-request-body@main
  with:
    githubToken: ${{ secrets.GITHUB_TOKEN }}
```

#### Input parameters

| Parameter | Description | Default |
| - | - | - |
| `githubToken` | Access token to manage GitHub repositories | **Required** |

### Check action SHA pinning

Validates that external GitHub Actions are pinned to SHA versions for security.

> [!IMPORTANT]
>
> This action will not raise an exception in default configuration and validates actions and workflows in `.github` folder by default.

**Action**: `backbase-common/gc-ai-workflows/check-action-pinning@main`

#### Usage

```yaml theme={"system"}
- uses: backbase-common/gc-ai-workflows/check-action-pinning@main
  with:
    path: ".github"
    fail-on-error: "false"
    skip-organisation-name: "backbase-common"
```

#### Input parameters

| Parameter | Description | Default |
| - | - | - |
| `path` | Relative path to GitHub actions location | `.github` |
| `fail-on-error` | Fail if violation is found | `false` |
| `skip-organisation-name` | Organization to skip during validation | `backbase-common` |

#### Output parameters

* `valid`: Validation result (`"true"` or `"false"`)
* `violations`: List of violations in format: `file path:external action`, comma-separated

### Resolve metadata

Resolves project version and metadata from `pyproject.toml` using `uv version`.

**Action**: `backbase-common/gc-ai-workflows/resolve-metadata@main`

#### Usage

```yaml theme={"system"}
- uses: backbase-common/gc-ai-workflows/resolve-metadata@main
  id: metadata
```

#### Output parameters

* `version`: Raw version from `uv version`
* `releaseVersion`: Release version (without dev/alpha/beta/rc)
* `nextVersion`: Next version (incremented patch with .dev0)
* `devVersion`: Development version with branch and commit info
* `buildVersion`: Build version (release or dev)
* `isStable`: Whether this is a stable version
* `major`, `minor`, `patch`: Version components
* `name`: Project name from git repository
* `projectKey`: Sonar project key
* `organization`: GitHub organization

### Setup promptfoo

Sets up Node.js and installs promptfoo globally for LLM prompt evaluation.

**Action**: `backbase-common/gc-ai-workflows/setup-promptfoo@main`

#### Usage

```yaml theme={"system"}
- uses: backbase-common/gc-ai-workflows/setup-promptfoo@main
  with:
    nodeVersion: "20"
```

#### Input parameters

| Parameter | Description | Default |
| - | - | - |
| `nodeVersion` | Node.js version to use | `20` |

## Next steps

* [Configure your workflows](https://agenticbanking.backbase.io/agentic-ai/ci-cd-workflows/configurations.md)
* [Build and publish workflow](https://agenticbanking.backbase.io/agentic-ai/ci-cd-workflows/build-publish-workflow.md)
* [Pull request check workflow](https://agenticbanking.backbase.io/agentic-ai/ci-cd-workflows/pull-request-workflow.md)
* [Release workflow](https://agenticbanking.backbase.io/agentic-ai/ci-cd-workflows/release-workflow.md)
