Checks CI/CD setup

Prerequisites for CI/CD

To configure Checks to run in a pipeline, retrieve key configuration inputs from your Checks account and Google Cloud project.

Target Checks account and app

When you run Checks in your CI/CD platform, you will need to assign the results to a Checks account and an app that you've connected to that Checks account. To do this, you'll need the Checks Account ID and App ID.

For your Account ID, visit your Account Settings page.

For your App ID, visit your App Settings page.

Authentication

A service account should be used when using Checks in an automation setup, such as CI/CD. For more information on how to create and configure a service account, see Authenticate the CLI.

If using one of the Checks CI/CD plugins, refer to the plugin's documentation for how to provide the credentials.

If using the Checks CLI within your CI/CD system, it is recommended to use CI environment variables to configure your JSON key. For example:

CHECKS_CREDENTIALS=/my/path/to/serviceaccount.json

Configure Checks to run in a CI/CD pipeline

Checks supports the following approaches:

  • Checks CI/CD plugins: Checks provides prebuilt plugins for several CI/CD platforms, including GitHub and fastlane. See the side navigation for more.
  • Checks CLI: Teams with more complex workflows, or using a build system without a Checks prebuilt plugin, can use the Checks CLI in their CI/CD pipeline. See Setting up using Checks CLI and Universal setup using Checks CLI for details.
  • Checks API: For teams with highly customized workflows, Checks offers a robust REST API. Use it to initiate scans, retrieve reports, and tailor the experience to your unique requirements. Find more information in the Checks API documentation.

Universal setup using Checks CLI

If a Checks plugin does not exist for your CI/CD platform, you can use the Checks CLI. The Checks CLI can be scripted directly by developers into any CI/CD platform that supports script execution workflow steps.

The Checks CLI can be scripted to:

  • Return non-zero error codes only when certain criteria are met, for example, exit with an error code only if high priority issues found. Note that the CLI will never return an error code; the developer must return error codes manually in the scripting step.
  • Output all of its data into JSON for more flexibility.

Here's an example of using the CLI in GitHub Actions on every commit, instead of the Checks CI/CD GitHub Action. We're also transforming the output to produce an error code when Checks finds priority issues:

name: Example workflow using Checks
run-name: ${ { github.actor } } is running Checks App Compliance GitHub Action
on: [push]
jobs:
  checks:
    runs-on: ubuntu-latest
    steps:
        uses: actions/checkout@v4
      - name: Checks App Compliance analysis
        run:
          echo 'Starting Checks App Compliance scan...'
          chmod +x ./checks
          ./checks report generate --binary-path=${CHECKS_BINARY_PATH} --app-id=${CHECKS_APP_ID} --account-id=${CHECKS_ACCOUNT_ID} --no-input --json  --wait-and-print-report > checks_results.json
          echo "Wrote App Compliance scan results to checks_results.json"
        env:
            # Replace all inputs with your configurations.
            CHECKS_CREDENTIALS: ${{ secrets.SERVICE_ACCOUNT_JSON }}
            CHECKS_APP_ID: "123456"
            CHECKS_ACCOUNT_ID: "654321"
            CHECKS_BINARY_PATH: "./app_release.apk"
      - name: Read JSON file
        uses: actions/github-script@v6
        with:
            script: |
                const fs = require('fs');
                const json = fs.readFileSync('./checks_results.json', 'utf8');
                const report = JSON.parse(json);

                console.log(`Generated report name: ${report.name}`);
                console.log(`Report console URL: ${report.resultsUri}`);

                const failingChecks = [];
                for (const check of report.checks) {
                    if (check.severity.toString() === 'PRIORITY' && check.state.toString() === 'FAILED') {
                        failingChecks.push(check);
                    }
                }

                if (failingChecks.length > 0) {
                    console.log(`${failingChecks.length} priority issue(s) detected: `);
                    for (const check of failingChecks) {
                        console.log(`Type: ${check.type}. Details: ${JSON.stringify(check)}`);
                    }
                    process.exit(1);
                }

Feedback

Do you have a CI/CD workflow that you'd like to see added to this guide? Let us know at checks-support@google.com.