Query GitHub organizations and repositories

Mondoo's github provider lets you use cnquery to query and inventory your GitHub organizations and repositories. You can explore repos, branches, teams, members, pull requests, issues, workflows, packages, and security settings for both your own organization and public open source projects your team depends on.

Requirements

To analyze your GitHub environment with cnquery, you must have:

cnquery installed on your workstation
A GitHub account with access to the organization or repositories you want to query
A personal access token or custom GitHub App credentials

Configure access to GitHub

To query GitHub organizations and repos, cnquery needs to authenticate. There are two ways to do this:

Option 1: Personal access token. This is easier to set up but isn't recommended for very large GitHub organizations. Continue reading below to learn how.
Option 2: Custom GitHub application credentials. This takes longer to set up but scales for very large GitHub organizations, with API rate limits as much as 3x higher than personal access tokens. To learn how, read Give cnquery access to GitHub using custom app credentials.

Create a personal access token

cnquery needs a personal access token to query a GitHub organization, public repo, or private repo. The token's level of access determines how much information cnquery can retrieve.

To learn how to create a personal access token, read Creating a personal access token in the GitHub documentation. We recommend creating a classic token with these scopes:

public_repo
read:org
read:repo_hook
admin:org_hook
read:project

Set the GITHUB_TOKEN environment variable

You supply your personal access token to cnquery using the GITHUB_TOKEN environment variable.

Linux / macOS

export GITHUB_TOKEN=<your personal access token>

Windows

$Env:GITHUB_TOKEN = "<personal-access-token>"

Connect to GitHub

Query an organization

To launch a cnquery shell into your GitHub organization:

cnquery shell github org YOUR-ORG

For YOUR-ORG, substitute the name of your GitHub organization.

Query a specific repository

To query a specific repository in your organization:

cnquery shell github repo YOUR-ORG/YOUR-REPO

For example, to query the docs repository in the mondoohq organization:

cnquery shell github repo mondoohq/docs

Query a public repository

You can query any public repository, even if you don't own it. This is useful for assessing open source projects your team depends on:

cnquery shell github repo kubernetes/kubernetes

Run queries from the command line

Instead of using the interactive shell, you can run queries directly from the command line using the -c flag:

cnquery run github org YOUR-ORG -c "github.organization.repositories { name visibility }"

This is useful for scripting and automation.

Discover capabilities with the `help` command

Once inside the shell, use the help command to learn what GitHub resources you can query. This command lists all the GitHub resources:

help github

From the resulting list, you can drill down further. For example, enter this command to list all the GitHub organization resources you can query:

help github.organization

Example queries

Organization

Check whether two-factor authentication is required for organization members:

cnquery> github.organization.twoFactorRequirementEnabled
github.organization.twoFactorRequirementEnabled: true

Retrieve organization details:

cnquery> github.organization { name defaultRepositoryPermission totalPrivateRepos totalPublicRepos }
github.organization: {
  name: "mondoohq"
  defaultRepositoryPermission: "read"
  totalPrivateRepos: 42
  totalPublicRepos: 15
}

Repositories

List all repositories with their visibility:

cnquery> github.organization.repositories { name visibility }
github.organization.repositories: [
  0: {
    name: "api-server"
    visibility: "private"
  }
  1: {
    name: "docs"
    visibility: "public"
  }
  ...
]

Find archived repositories:

cnquery> github.organization.repositories.where( archived == true ) { name }
github.organization.repositories.where: [
  0: {
    name: "legacy-dashboard"
  }
  ...
]

Retrieve details about a specific repository:

cnquery> github.repository { name description visibility stargazersCount forksCount hasIssues hasWiki }
github.repository: {
  name: "docs"
  description: "Mondoo documentation"
  visibility: "public"
  stargazersCount: 128
  forksCount: 34
  hasIssues: true
  hasWiki: false
}

Branches and branch protection

List branches for a repository and check their protection status:

cnquery> github.repository.branches { name isDefault isProtected }
github.repository.branches: [
  0: {
    name: "main"
    isDefault: true
    isProtected: true
  }
  1: {
    name: "feature-auth"
    isDefault: false
    isProtected: false
  }
  ...
]

Find repositories without branch protection on the default branch:

cnquery> github.organization.repositories.where( defaultBranch.protectionRules == null ) { name }
github.organization.repositories.where: [
  0: {
    name: "test-sandbox"
  }
  ...
]

Members and teams

List organization members:

cnquery> github.organization.members { login }
github.organization.members: [
  0: {
    login: "alice-johnson"
  }
  1: {
    login: "bob-smith"
  }
  ...
]

List teams and their members:

cnquery> github.organization.teams { name members { login } }
github.organization.teams: [
  0: {
    name: "Engineering"
    members: [
      0: {
        login: "alice-johnson"
      }
      1: {
        login: "bob-smith"
      }
    ]
  }
  ...
]

Pull requests

List open pull requests for a repository:

cnquery> github.repository.openMergeRequests { title state owner { login } createdAt }
github.repository.openMergeRequests: [
  0: {
    title: "Add user authentication"
    state: "open"
    owner: {
      login: "alice-johnson"
    }
    createdAt: 2025-01-10 14:30:00 +0000 UTC
  }
  ...
]

Issues

List open issues for a repository:

cnquery> github.repository.openIssues { title state createdAt }
github.repository.openIssues: [
  0: {
    title: "Update login page styling"
    state: "open"
    createdAt: 2025-01-08 09:15:00 +0000 UTC
  }
  ...
]

Workflows

List GitHub Actions workflows:

cnquery> github.repository.workflows { name state path }
github.repository.workflows: [
  0: {
    name: "CI"
    state: "active"
    path: ".github/workflows/ci.yml"
  }
  1: {
    name: "Release"
    state: "active"
    path: ".github/workflows/release.yml"
  }
  ...
]

Webhooks

List organization webhooks:

cnquery> github.organization.webhooks { name active events }
github.organization.webhooks: [
  0: {
    name: "web"
    active: true
    events: [
      0: "push"
      1: "pull_request"
    ]
  }
  ...
]

Packages

List packages in the organization:

cnquery> github.organization.packages { name packageType visibility }
github.organization.packages: [
  0: {
    name: "api-client"
    packageType: "npm"
    visibility: "private"
  }
  1: {
    name: "base-image"
    packageType: "container"
    visibility: "public"
  }
  ...
]

Filter results

You can filter results based on any fields. Specify the criteria using the where function and standard boolean operators.

For example, this query filters repository branches to show only protected branches:

cnquery> github.repository.branches.where( protected == true ) { name }
github.repository.branches.where: [
  0: {
    name: "main"
  }
]

Learn more

For a list of all the GitHub resources and fields you can query, read the Mondoo GitHub Resource Pack Reference.
To learn more about how the MQL query language works, read Write Effective MQL.

Query GitHub organizations and repositories

On this page