CAPA pipeline deployment fails due to missing environment variables

QMS Qualio
, , , , , , , ,
1

Our GitHub Actions pipeline for deploying the CAPA module to qual-2022.2 keeps failing at the deployment step. The error indicates missing environment variables, but I’ve verified they’re set in our repository secrets.

The pipeline configuration references secrets for database connection and API endpoints, but the deployment script can’t seem to access them during runtime. We’re blocked from releasing critical CAPA fixes to production.

env:
  DB_HOST: ${{ secrets.QUALIO_DB_HOST }}
  API_KEY: ${{ secrets.QUALIO_API_KEY }}

Error message:


Error: Required environment variable 'QUALIO_DB_HOST' not found
Deployment failed at step: database-migration

I’ve checked the secrets manager integration and the variable names match exactly. The same pipeline works fine for our document-control module. Has anyone encountered this with CAPA deployments? Is there something specific about how CAPA handles environment configuration during CI/CD?

2

The CAPA module in qual-2022.2 has enhanced security requirements that affect how it reads environment variables during deployment. Unlike document-control, CAPA validates all connection strings against a whitelist defined in the deployment manifest. Your secrets need to be mapped through an intermediate configuration file that gets validated before the actual deployment step runs. This is part of the compliance controls for CAPA data handling. Check if your pipeline includes the pre-deployment validation stage that generates the validated config.

3

We had this exact problem last month. The root cause was the pipeline environment variable mapping not aligning with CAPA’s expected variable format. Here’s what fixed it for us:

First, you need to understand that CAPA deployment scripts in qual-2022.2 expect variables in a specific namespace format. Your secrets manager integration needs to map GitHub secrets to the CAPA-expected format through an intermediate configuration step.

Add this validation and mapping step before your deployment:

- name: Prepare CAPA Config
  run: |
    echo "CAPA_DB_CONNECTION=${DB_HOST}" >> $GITHUB_ENV
    echo "CAPA_API_ENDPOINT=${API_KEY}" >> $GITHUB_ENV

The key issue is that CAPA looks for CAPA_* prefixed variables, not the raw secret names. Your CI/CD config syntax needs to include this mapping layer.

Second, verify your deployment manifest includes these variables in the allowlist:

{
  "allowedEnvVars": [
    "CAPA_DB_CONNECTION",
    "CAPA_API_ENDPOINT"
  ]
}

Third, ensure your secrets manager integration in GitHub Actions has the proper permissions scope. CAPA deployment requires repo and workflow scopes to access organization-level secrets.

The pipeline environment variable mapping is critical because CAPA validates every variable against its security schema before allowing deployment to proceed. This prevents unauthorized configuration changes from bypassing audit trails.

For secrets manager integration, use GitHub’s environment protection rules to require approval before variables are exposed to the deployment job. This creates the audit trail that CAPA compliance requires.

Finally, update your CI/CD config syntax to include the CAPA-specific deployment hooks:

jobs:
  deploy-capa:
    environment: production
    steps:
      - name: Validate CAPA Environment
        run: node scripts/validate-capa-env.js
      - name: Deploy CAPA Module
        run: npm run deploy:capa

The validation script should verify all three focus areas: proper variable mapping, secrets manager connectivity, and config syntax compliance. This approach has worked reliably for us across multiple CAPA deployments to qual-2022.2 and qual-2023.1.

4

Thanks for the suggestions. I looked into the environment scoping but we’re already using job-level environment definitions. The validation stage is interesting - I don’t see that in our current pipeline. Could you point me to documentation on the CAPA deployment manifest requirements?

5

I ran into something similar with qual-2022.2 CAPA deployments. Check if your workflow is using the correct environment context. CAPA module has stricter requirements for environment variable scoping. Try explicitly defining the environment in your job step rather than at the workflow level.

6

The manifest is defined in the CAPA module deployment package under /config/deployment-manifest.json. You need to ensure your GitHub Actions workflow includes a step that reads your secrets, validates them against the manifest schema, and writes them to a temporary config file that the deployment script consumes. This two-stage approach prevents direct secret injection which could bypass audit logging.

7

We switched from GitHub Actions to Azure Pipelines for CAPA deployments specifically because of this issue. Azure’s variable groups handle the secrets manager integration more cleanly for Qualio modules. But if you’re committed to GitHub Actions, make sure you’re using the latest action versions - there was a bug in earlier versions where environment variables weren’t properly inherited by nested deployment scripts.