Skip to main content

actions

Shared, reusable GitHub Actions for Marqo respositories.

See EDR-6: Consistent code style tools for more details.

Context​

  • Some workflows will require elevated permissions to function correctly (e.g. pull-requests: write to add PR comments).

Workflows​

The following workflows are available. See each example for instructions on how to use them in your repository.

Lint​

The lint workflow analyzes the codebase for common issues and style violations.

on: pull_request
jobs:
  lint:
    permissions:
      contents: read
      pull-requests: write
    uses: marqo-ai/actions/.github/workflows/lint.yaml@main

Claude Code Review​

The Claude Code Review workflow runs an AI-powered code review on pull requests using Claude.

on:
  pull_request:
    types: [opened, synchronize]
jobs:
  claude-review:
    permissions:
      contents: read
      pull-requests: read
      issues: read
      id-token: write
    uses: marqo-ai/actions/.github/workflows/claude_code_review.yaml@main
    secrets: inherit

Required Secrets:

  • CLAUDE_CODE_OAUTH_TOKEN: OAuth token for Claude Code

Optional Inputs:

  • model: Claude model to use (default: claude-opus-4-6)
  • allowed_tools: Comma-separated list of allowed tools (has sensible defaults for code review)
  • request_changes: Submit REQUEST_CHANGES instead of advisory COMMENT reviews when Claude finds issues (default: false)
  • review_drafts: Run on draft pull requests too (default: false)
  • review_instructions: Append repository-specific review instructions to the shared review prompt

SonarQube Scan​

The SonarQube scan workflows run code quality analysis and push coverage metrics to Atlassian Compass.

Python Components​

The Python workflow performs SonarQube scans and pushes coverage metrics to Compass. The calling repository is responsible for running tests and uploading the coverage artifact.

on:
  push:
    branches: [main]
  pull_request:

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      # ... your test setup and execution ...
      - name: Upload coverage
        uses: actions/upload-artifact@v4
        with:
          name: coverage
          path: dist/coverage/python/coverage.xml

  sonar-scan-python:
    needs: test
    uses: marqo-ai/actions/.github/workflows/sonarqube_scan_python.yaml@main
    with:
      components: '["controller", "my-service"]'  # JSON array of component names
      coverage-artifact-name: "coverage"  # Name of the artifact uploaded above
    secrets: inherit

Required Inputs:

  • components: JSON array of component names to scan (e.g., '["controller"]')
  • coverage-artifact-name: Name of the coverage artifact uploaded by the calling workflow
  • sonar-host-url: SonarQube host URL
  • sonar-token: SonarQube authentication token
  • compass-api-token: API token for Atlassian Compass
  • compass-username: Username for Atlassian Compass API authentication
  • compass-cloud-id: Cloud ID for Atlassian Compass
  • compass-api-url: Base URL for Compass GraphQL API

Optional Inputs:

  • component-path-prefix: Path prefix for components (default: "components/")
  • python-version-scan: Python version for scan and coverage filtering (default: "3.11")
  • runner: Runner for the scan job (default: "ubuntu-latest")
  • metric-name: Name of the metric to push (default: "Unit test coverage")
  • repo-url: Repository URL (defaults to current repository)

TypeScript Components​

The TypeScript workflow runs tests, builds, performs SonarQube scans, and pushes coverage metrics to Compass.

on:
  push:
    branches: [main]
  pull_request:

jobs:
  sonar-scan-ts:
    uses: marqo-ai/actions/.github/workflows/sonarqube_scan_ts.yaml@main
    with:
      components: '["admin_worker", "search_proxy"]'  # JSON array of component names
    secrets: inherit

Required Inputs:

  • components: JSON array of component names to scan (e.g., '["admin_worker"]')
  • sonar-host-url: SonarQube host URL
  • sonar-token: SonarQube authentication token
  • compass-api-token: API token for Atlassian Compass
  • compass-username: Username for Atlassian Compass API authentication
  • compass-cloud-id: Cloud ID for Atlassian Compass
  • compass-api-url: Base URL for Compass GraphQL API

Optional Inputs:

  • component-path-prefix: Path prefix for components (default: "components/")
  • node-version: Node.js version to use (default: "22")
  • runner: Runner for the job (default: "ubuntu-latest")
  • metric-name: Name of the metric to push (default: "Unit test coverage")
  • repo-url: Repository URL (defaults to current repository)

Prerequisites:

  • Each component must have a sonar-project.properties file in its directory
  • SonarQube project configuration must be set up
  • Compass secrets and variables must be configured in your repository

Caveats​

You may set the reusable actions to be required checks in your repository settings. This will ensure that the actions succeed before any pull requests are merged. However if the IDs of the checks change, you will be unable to satisfy those requirements and will need to update your repository settings with the new IDs. See troubleshooting docs for more details.

Other Integrations​

VS Code​

If using VS Code, install the following extensions:

Set Ruff as the default formatter for Python, and you can uninstall any other Python formatters (e.g. Black).

pre-commit​

To use Ruff as a pre-commit check, add the following to your .pre-commit-config.yaml:

repos:
    - repo: https://github.com/astral-sh/ruff-pre-commit
      rev: v0.4.9
      hooks:
          - id: ruff
            args:
                - --fix
                - --select
                - I
          - id: ruff-format

Task Runners​

Python​

To run these actions locally, you can use the invoke task runner (pip install invoke).

Create a tasks.py file in the root of your repository with the following content:

from invoke.tasks import task


@task
def lint(c, fix=False, types=True):
    """Run Ruff linter."""
    cmd = "ruff check"
    if fix:
        cmd += " --fix"
    c.run(cmd)
    if types:
        print("Checking types...")
        c.run("pyright")


@task
def format(c):
    """Run Ruff formatter."""
    c.run("ruff format")

Web​

Web tasks are typically run via package.json scripts and npm run. npm install -D @biomejs/biome prettier and add the following scripts:

{
  "scripts": {
    "lint": "biome lint .",
    "format": "biome format --write ./src && prettier --write '**/*.{css,md}'",
  }
}

Note that Biome only formats JS(X), TS(X), and JSON, so Prettier is used for other relevant file types.