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

# 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](/agentic-ai/ci-cd-workflows/configurations#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](/agentic-ai/ci-cd-workflows/configurations#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](/agentic-ai/ci-cd-workflows/configurations)
* [Build and publish workflow](/agentic-ai/ci-cd-workflows/build-publish-workflow)
* [Pull request check workflow](/agentic-ai/ci-cd-workflows/pull-request-workflow)
* [Release workflow](/agentic-ai/ci-cd-workflows/release-workflow)