drivers-github-tools

Important

This Repository is NOT a supported MongoDB product

This repository contains GitHub Actions that are common to drivers.

See the How To: Set up Secure Release Process using GitHub Action internal wiki for guidance.

Working on Actions

Many of the actions in this repo depend on one another. Internal action-to-action references use GitHub Actions' $/ self-repository syntax (e.g. uses: $/setup), which resolves to the repository and ref of the file containing the reference: this repo, at the exact commit running, for anything that executes here. No version pin or checkout is needed. Use $/ for any new internal reference instead of a pinned mongodb-labs/drivers-github-tools/...@v3 reference.

The one exception is node/release_template.yml: it's a template that node/generate_release.mjs renders into Node.js driver repos as their own release workflow, so $/ there would resolve to the driver repo instead of this one. It must keep pinned owner/repo/path@vX references.

Consuming Actions

It is recommended that you use Dependabot and use an explicit reference when using these actions. This will allow Dependabot to update to a more recent sha and allow you to accept updates to the actions as needed.

Because $/ resolves relative to the pinned ref (see "Working on Actions" above), pinning an old sha of a top-level action also freezes the sub-actions it calls internally at that same point, rather than always picking up their latest tagged version. For example, pinning full-report to an old sha means it also calls that old sha's sbom, authorized-pub, code-scanning-export, and compliance-report. Bump your pin to pick up sub-action updates too.

Note

Through v3, this repo maintains floating major-version tags (e.g. v3) that move to the latest commit on main. Starting with v4, releases only get immutable vX.Y.Z tags; there is no floating v4 tag. Pin to an exact vX.Y.Z tag (or its resolved commit SHA) once you move to v4.

Example dependabot.yml:

version: 2
updates:
  - package-ecosystem: "github-actions"
    directory: "/"
    schedule:
      interval: "weekly"
    groups:
      actions:
        patterns:
          - "*"

Example usage with references:

- name: secure-checkout
  uses: mongodb-labs/drivers-github-tools/secure-checkout@40b8ff3c0decd1388587fcc3d0a36d4818a054a6  # v2
  with:
    app_id: ${{ vars.APP_ID }}
    private_key: ${{ secrets.APP_PRIVATE_KEY }}

Basic Actions

Secure Checkout

This action will perform a checkout with the GitHub App credentials.

- name: secure-checkout
  uses: mongodb-labs/drivers-github-tools/secure-checkout@v3
  with:
    app_id: ${{ vars.APP_ID }}
    private_key: ${{ secrets.APP_PRIVATE_KEY }}

By default it will use the current ${{github.ref}} if the ref parameter is not given. It will write the secure global variable GH_TOKEN that can be used with the gh cli.

Setup

There is a common setup action that is meant to be run before all other actions. It handles fetching secrets from AWS Secrets Manager, signing into ECR, setting up Garasign credentials, and setting up environment variables used in other actions. The action requires id-token: write permissions.

- name: setup
  uses: mongodb-labs/drivers-github-tools/setup@v3
  with:
    aws_role_arn: ${{ secrets.AWS_ROLE_ARN }}
    aws_region_name: ${{ vars.AWS_REGION_NAME }}
    aws_secret_id: ${{ secrets.AWS_SECRET_ID }}

Note

You must use the actions/checkout action prior to calling the setup action, Since the setup action sets up git config that would be overridden by the actions/checkout action

The following keys MUST be defined in the AWS_SECRET_ID vault: garasign-username, garasign-password, gpg-key-id. If uploading to an S3 bucket, also define release-assets-bucket.

Signing tools

These actions are used to sign artifacts using the team's GPG key.

git-sign

Use this action to create signed git artifacts:

- name: Setup
  uses: mongodb-labs/drivers-github-tools/setup@v3
  with:
    ...

- name: Create signed commit
  uses: mongodb-labs/drivers-github-tools/git-sign@v3
  with:
    command: "git commit -m 'Commit' -s --gpg-sign=${{ env.GPG_KEY_ID }}"

- name: Create signed tag
  uses: mongodb-labs/drivers-github-tools/git-sign@v3
  with:
    command: "git tag -m 'Tag' -s --local-user=${{ env.GPG_KEY_ID }} -a <tag>"

bump-version

This is a convenience action to bump the version, create a signed commit, and push the commit unless push_commit is disabled. You can override the commit message format if desired. The version bump script should accept a new version as an argument and update the version accordingly.

- name: Bump version
  uses: mongodb-labs/drivers-github-tools/bump-version@v3
  with:
    version: ${{ inputs.version }}
    version_bump_script: "bash ./my-bump-version-script.sh"

tag-version

This is a convenience action to create a signed tag, optionally verify the tag, and push the tag unless push_tag is disabled. You can override the tag format and the tag message format if desired.

- name: Tag version
  uses: mongodb-labs/drivers-github-tools/tag-version@v3
  with:
    version: ${{ inputs.version }}

gpg-sign

This action is used to create detached signatures for files:

- name: Setup
  uses: mongodb-labs/drivers-github-tools/setup@v3
  with:
    ...

- name: Create detached signature
  uses: mongodb-labs/drivers-github-tools/gpg-sign@v3
  with:
    filenames: somefile.ext

The action will create a signature file somefile.ext.sig in the working directory.

You can also supply a glob pattern to sign a group of files:

- name: Setup
  uses: mongodb-labs/drivers-github-tools/setup@v3
  with:
    ...

- name: Create detached signature
  uses: mongodb-labs/drivers-github-tools/garasign/gpg-sign@v1
  with:
    filenames: dist/*

Reporting tools

The following tools are meant to aid in generating Software Security Development Lifecycle reports associated with a product release.

Authorized Publication

This action will create a record of authorized publication on distribution channels. It will create the file $S3_ASSETS/authorized_publication.txt

- name: Setup
  uses: mongodb-labs/drivers-github-tools/setup@v3
  with:
    ...

- name: Create Authorized Publication Report
  uses: mongodb-labs/drivers-github-tools/authorized-pub@v3
  with:
    product_name: Mongo Python Driver
    release_version: ${{ github.ref_name }}
    filenames: dist/*
    token: ${{ github.token }}

Software Bill of Materials (SBOM)

This action will download an Augmented SBOM file in $RELEASE_ASSETS/sbom.json.

- name: Setup
  uses: mongodb-labs/drivers-github-tools/setup@v3
  with:
    ...

- name: Create SBOM
  uses: mongodb-labs/drivers-github-tools/sbom@v3
  with:
    sbom_in_path: sbom.json

Code Scanning Alerts

This action will export all dismissed and open alerts to a SARIF file. By default, this file is named code-scanning-alerts.json and placed in the working directory.

- name: Setup
  uses: mongodb-labs/drivers-github-tools/setup@v3
  with:
    ...

- name: Export Code Scanning Alerts
  uses: mongodb-labs/drivers-github-tools/code-scanning-export@v3

Compliance Report

This action will generate the SSDLC compliance report in the S3_ASSETS folder, called ssdlc_compliance_report.md.

- name: Setup
  uses: mongodb-labs/drivers-github-tools/setup@v3
  with:
    ...

- name: Generate compliance report
  uses: mongodb-labs/drivers-github-tools/compliance-report@v3

There are several ways to specify the security report:

• By specifying an absolute URL starting with https
• By specifying a relative path, which is then linked to the corresponding git blob for the tagged version
• By adding the security-report-url to the AWS Secrets Vault

Security Actions

CodeQL Analysis

This action runs CodeQL analysis for a single language. It includes checkout, Python setup (only when language: python), CodeQL initialization, an optional manual build step, and the analysis itself — centralising the pinned CodeQL action version so Dependabot only needs to update one file across all repos using the action.

jobs:
  analyze:
    runs-on: ubuntu-latest
    timeout-minutes: 360
    permissions:
      security-events: write
      contents: read
      actions: read
    strategy:
      fail-fast: false
      matrix:
        include:
          - language: cpp
            build-mode: manual
            manual-build-command: make
          - language: python
            build-mode: none
          - language: actions
            build-mode: none
    steps:
      - uses: mongodb-labs/drivers-github-tools/codeql@v3
        with:
          language: ${{ matrix.language }}
          build-mode: ${{ matrix.build-mode }}
          manual-build-command: ${{ matrix.manual-build-command }}
          config: |
            paths-ignore:
              - 'doc/**'
              - 'test/**'

Pass ref when the workflow is invoked via workflow_call with a specific git ref:

      - uses: mongodb-labs/drivers-github-tools/codeql@v3
        with:
          language: ${{ matrix.language }}
          build-mode: ${{ matrix.build-mode }}
          manual-build-command: ${{ matrix.manual-build-command }}
          ref: ${{ inputs.ref }}

Other Common Actions

Full Report

This action is a convenience function to handle all of the SSDLC reports and put them in the S3_ASSETS folder. This composite action runs the authorized-pub, sbom, code-scanning-export, and compliance-report actions.

- name: Setup
  uses: mongodb-labs/drivers-github-tools/setup@v3
  with:
    ...

- name: Generate SSDLC Reports
  uses: mongodb-labs/drivers-github-tools/full-report@v3
  with:
    product_name: winkerberos
    release_version: ${{ inputs.version }}
    sbom_in_path: sbom.json
    dist_filenames: dist/*

Upload S3 assets

A number of scripts create files in the tmp/s3_assets folder, which then can be uploaded to the product's S3 bucket:

- name: Setup
  uses: mongodb-labs/drivers-github-tools/setup@v3
  with:
    ...

- name: Upload S3 assets
  uses: mongodb-labs/drivers-github-tools/upload-s3-assets@v3
  with:
    version: <release version>
    product_name: <product_name>

Optionally, you can specify which files to upload using the filenames input. By default, all files in the S3 directory are uploaded. When the dry_run input is set to anything other than false, no files are uploaded, but instead the filename along with the resulting location in the bucket is printed.

Create Release Branch

Use this action to create a release branch and populate it with metadata. It will update EVERGREEN_PROJECT env variable in the release workflow file, bump the version to a prerelease version, and push the changes.

- name: Setup
  uses: mongodb-labs/drivers-github-tools/setup@v3
  with:
    ...

- name: Create Release Branch
  uses: mongodb-labs/drivers-github-tools/create-branch@v3
  with:
    # user inputs
    branch: ...
    version: ...
    base_ref: <optional>
    push_changes: <whether to push changes>
    # other inputs
    version_bump_script: <path/to/version/bump/script>
    evergreen_project: <name of evergreen release project>

Validate Submodules

Use this action to validate that submodule commits are present on the upstream branch and do not regress from the target branch. It is intended to run on pull requests and merge groups.

Each submodule entry in .gitmodules must declare a branch field pointing to the upstream branch to validate against:

[submodule "specifications"]
	path = tests/specifications
	url = https://github.com/mongodb/specifications
	branch = master

on:
  merge_group:
  pull_request:

jobs:
  validate-submodules:
    runs-on: ubuntu-latest
    steps:
      - name: Validate submodule commits
        uses: mongodb-labs/drivers-github-tools/validate-submodules@v3
        with:
          token: ${{ github.token }}

Python Actions

Python helper actions have their own READMEs:

• python/ covers setup, pre-publish, post-publish, and uv lock updates for the Python drivers.
• python-labs/ covers pre-publish and post-publish for MongoDB Labs projects, without the SSDLC assets and S3 upload.