From db96b9cc4fb5b3a625300c00b0fa356dc50a68b5 Mon Sep 17 00:00:00 2001 From: Sam Browning <106113886+sabrowning1@users.noreply.github.com> Date: Fri, 6 Mar 2026 09:55:06 -0500 Subject: [PATCH 1/4] [EDI] Publishing and using CodeQL packs (#60066) --- .../scan-from-the-command-line/index.md | 4 +- .../publish-and-use-packs.md | 173 ++++++++++++++++ ...-codeql-cli.md => write-custom-queries.md} | 24 +-- .../codeql/codeql-cli/codeql-query-packs.md} | 196 ++---------------- .../code-scanning/codeql/codeql-cli/index.md | 1 + .../codeql/codeql-queries/index.md | 3 +- .../customize-code-scanning/index.md | 1 - 7 files changed, 202 insertions(+), 200 deletions(-) create mode 100644 content/code-security/how-tos/scan-code-for-vulnerabilities/scan-from-the-command-line/publish-and-use-packs.md rename content/code-security/how-tos/scan-code-for-vulnerabilities/scan-from-the-command-line/{writing-and-sharing-custom-queries-for-the-codeql-cli.md => write-custom-queries.md} (73%) rename content/code-security/{tutorials/customize-code-scanning/publishing-and-using-codeql-packs.md => reference/code-scanning/codeql/codeql-cli/codeql-query-packs.md} (54%) diff --git a/content/code-security/how-tos/scan-code-for-vulnerabilities/scan-from-the-command-line/index.md b/content/code-security/how-tos/scan-code-for-vulnerabilities/scan-from-the-command-line/index.md index d42008b341ed..949f7f7206cf 100644 --- a/content/code-security/how-tos/scan-code-for-vulnerabilities/scan-from-the-command-line/index.md +++ b/content/code-security/how-tos/scan-code-for-vulnerabilities/scan-from-the-command-line/index.md @@ -12,14 +12,14 @@ topics: - CodeQL children: - /setting-up-the-codeql-cli - - /writing-and-sharing-custom-queries-for-the-codeql-cli + - /write-custom-queries + - /publish-and-use-packs - /testing-custom-queries - /testing-query-help-files - /download-databases - /check-out-source-code - /specifying-command-options-in-a-codeql-configuration-file - /creating-database-bundle-for-troubleshooting - redirect_from: - /code-security/codeql-cli/using-the-codeql-cli - /code-security/codeql-cli/getting-started-with-the-codeql-cli diff --git a/content/code-security/how-tos/scan-code-for-vulnerabilities/scan-from-the-command-line/publish-and-use-packs.md b/content/code-security/how-tos/scan-code-for-vulnerabilities/scan-from-the-command-line/publish-and-use-packs.md new file mode 100644 index 000000000000..7e9b01ec9b37 --- /dev/null +++ b/content/code-security/how-tos/scan-code-for-vulnerabilities/scan-from-the-command-line/publish-and-use-packs.md @@ -0,0 +1,173 @@ +--- +title: Publishing and using CodeQL packs +shortTitle: Publish and use packs +intro: Share or download a {% data variables.product.prodname_codeql %} pack, then analyze your {% data variables.product.prodname_codeql %} database. +product: '{% data reusables.gated-features.codeql %}' +versions: + fpt: '*' + ghes: '*' + ghec: '*' +topics: + - Code Security + - Code scanning + - CodeQL +redirect_from: + - /code-security/codeql-cli/publishing-and-using-codeql-packs + - /code-security/codeql-cli/using-the-codeql-cli/publishing-and-using-codeql-packs + - /code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/publishing-and-using-codeql-packs + - /code-security/tutorials/customize-code-scanning/publishing-and-using-codeql-packs +contentType: how-tos +--- + +{% ifversion ghec or ghes %} + +## Working with {% data variables.product.prodname_codeql %} packs on {% data variables.enterprise.gh_enterprise %} + +By default, the {% data variables.product.prodname_codeql_cli %} expects to download {% data variables.product.prodname_codeql %} packs from and publish packs to the {% data variables.product.prodname_container_registry %} on {% data variables.product.prodname_dotcom_the_website %}. However, you can also work with {% data variables.product.prodname_codeql %} packs in a {% data variables.product.prodname_container_registry %} on {% data variables.enterprise.gh_enterprise %} by creating a `qlconfig.yml` file to tell the CLI which {% data variables.product.prodname_container_registry %} to use for each pack. + +Create a `~/.codeql/qlconfig.yml` file on Linux/MacOS or `%HOMEPATH%\.codeql\qlconfig.yml` on Windows using your preferred text editor, and add entries to specify which registry to use for one or more package name patterns. +For example, the following `qlconfig.yml` file associates all packs with the {% data variables.product.prodname_container_registry %} at `{% data variables.enterprise.gh_enterprise_domain %}`, except packs matching `codeql/\*` or the `other-org/*` organization, which are associated with the {% data variables.product.prodname_container_registry %} on {% data variables.product.prodname_dotcom_the_website %}: + +```yaml +registries: +- packages: + - 'codeql/*' + - 'other-org/*' + # {% data variables.product.prodname_container_registry %} on {% data variables.product.prodname_dotcom_the_website %} + url: https://ghcr.io/v2/ +- packages: '*' + # {% data variables.product.prodname_container_registry %} hosted at `{% data variables.enterprise.gh_enterprise_domain %}` + url: {% data variables.enterprise.gh_enterprise_container_registry %} +``` + +The {% data variables.product.prodname_codeql_cli %} will determine which registry to use for a given package name by finding the first item in the `registries` list with a `packages` property that matches that package name. +This means that you’ll generally want to define the most specific package name patterns first. The `packages` property may be a single package name, a glob pattern, or a YAML list of package names and glob patterns. + +The `registries` list can also be placed inside a `codeql-workspace.yml` file. Doing so will allow you to define the registries to be used within a specific workspace, so that it can be shared amongst other {% data variables.product.prodname_codeql %} users of the workspace. The `registries` list in `codeql-workspace.yml` will be merged with and take precedence over the list in the global `qlconfig.yml`. For more information about `codeql-workspace.yml`, see [AUTOTITLE](/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/about-codeql-workspaces#about-codeql-workspaces). + +You can now use `codeql pack publish`, `codeql pack download`, and `codeql database analyze` to manage packs on {% data variables.enterprise.gh_enterprise %}. + +{% endif %} + +## Authenticating to {% data variables.product.github %} {% data variables.product.prodname_container_registries %} + +You can publish packs and download private packs by authenticating to the appropriate {% data variables.product.github %} {% data variables.product.prodname_container_registry %}. + +{% ifversion ghec or ghes %} + +### Authenticating to {% data variables.product.prodname_container_registries %} on {% data variables.product.prodname_dotcom_the_website %} + +{% endif %} + +You can authenticate to the {% data variables.product.prodname_container_registry %} in two ways: + +1. Pass the `--github-auth-stdin` option to the {% data variables.product.prodname_codeql_cli %}, then supply a {% data variables.product.prodname_github_apps %} token or {% data variables.product.pat_generic %} via standard input. +1. Set the `GITHUB_TOKEN` environment variable to a {% data variables.product.prodname_github_apps %} token or {% data variables.product.pat_generic %}. + +{% ifversion ghec or ghes %} + +### Authenticating to {% data variables.product.prodname_container_registries %} on {% data variables.enterprise.gh_enterprise %} + +Similarly, you can authenticate to a {% data variables.product.prodname_container_registry %} on {% data variables.enterprise.gh_enterprise %}, or authenticate to multiple registries simultaneously (for example, to download or run private packs from multiple registries) in two ways: + +1. Pass the `--registries-auth-stdin` option to the {% data variables.product.prodname_codeql_cli %}, then supply a registry authentication string via standard input. +1. Set the `CODEQL_REGISTRIES_AUTH` environment variable to a registry authentication string. + +A registry authentication string is a comma-separated list of `=` pairs, where `registry-url` is a {% data variables.product.prodname_container_registry %} URL, such as `{% data variables.enterprise.gh_enterprise_container_registry %}`, and `token` is a {% data variables.product.prodname_github_apps %} token or {% data variables.product.pat_generic %} for that {% data variables.product.prodname_container_registry %}. +This ensures that each token is only passed to the {% data variables.product.prodname_container_registry %} you specify. + +For example, the following registry authentication string specifies that the {% data variables.product.prodname_codeql_cli %} should authenticate as follows: + +* Use the token `` to authenticate to {% data variables.product.prodname_container_registry %} on {% data variables.product.prodname_dotcom_the_website %}. +* Use the token `` to authenticate to the {% data variables.product.prodname_container_registry %} for the enterprise at `{% data variables.enterprise.gh_enterprise_container_registry %}`. + +```shell +https://ghcr.io/v2/=,{% data variables.enterprise.gh_enterprise_container_registry %}= +``` + +{% endif %} + +## Publishing your {% data variables.product.prodname_codeql %} pack + +To share your {% data variables.product.prodname_codeql %} pack with other people, you can publish it to the {% data variables.product.prodname_container_registry %}. + +### Configuring the `qlpack.yml` file before publishing + +{% data reusables.code-scanning.codeql-cli-version-ghes %} + +You can check and modify the configuration details of your {% data variables.product.prodname_codeql %} pack prior to publishing. Open the `qlpack.yml` file in your preferred text editor. + +```yaml +library: # set to true if the pack is a library. Set to false or omit for a query pack +name: / +version: +description: +defaultSuite: # optional, one or more queries in the pack to run by default + - query: /query-file>.ql +defaultSuiteFile: default-queries.qls # optional, a pointer to a query-suite in this pack +license: # optional, the license under which the pack is published +dependencies: # map from CodeQL pack name to version range +``` + +* `name:` must follow the `/` format, where `` is the {% data variables.product.prodname_dotcom %} organization that you will publish to and `` is the name for the pack. + +* A maximum of one of `defaultSuite` or `defaultSuiteFile` is allowed. These are two different ways to define a default query suite to be run, the first by specifying queries directly in the qlpack.yml file and the second by specifying a query suite in the pack. + +### Running `codeql pack publish` + +When you are ready to publish a pack to the {% data variables.product.prodname_dotcom %} {% data variables.product.prodname_container_registry %}, you can run the following command in the root of the pack directory: + +```shell +codeql pack publish +``` + +The published package will be displayed in the packages section of {% data variables.product.prodname_dotcom %} organization specified by the scope in the `qlpack.yml` file. + +> [!NOTE] +> If you're publishing model packs to the {% data variables.product.prodname_dotcom %} {% data variables.product.prodname_container_registry %} in order to extend coverage to all repositories in an organization as part of a default setup configuration, then you need to ensure that repositories running code scanning can access those model packs. For more information, see [AUTOTITLE](/code-security/code-scanning/managing-your-code-scanning-configuration/editing-your-configuration-of-default-setup) and [AUTOTITLE](/packages/learn-github-packages/configuring-a-packages-access-control-and-visibility). + +## Downloading an existing {% data variables.product.prodname_codeql %} pack + +To run a pack that someone else has created, you must first download it by running the following command: + +```shell +codeql pack download /@x.x.x +``` + +* ``: the name of the {% data variables.product.prodname_dotcom %} organization that you will download from. +* ``: the name for the pack that you want to download. +* `@x.x.x`: an optional version number. If omitted, the latest version will be downloaded. + +This command accepts arguments for multiple packs. + +If you write scripts that specify a particular version number of a +query pack to download, keep in mind that when you update your version of +{% data variables.product.prodname_codeql %} to a newer one, you may +also need to switch to a newer version of the query pack. Newer +versions of {% data variables.product.prodname_codeql %} _may_ provide +degraded performance when used with query packs that have been pinned +to a very old version. For more information, see [About {% data variables.product.prodname_codeql %} +pack compatibility](#about-codeql-pack-compatibility). + +## Using a {% data variables.product.prodname_codeql %} pack to analyze a {% data variables.product.prodname_codeql %} database + +To analyze a {% data variables.product.prodname_codeql %} database with a {% data variables.product.prodname_codeql %} pack, run the following command: + +```shell +codeql database analyze /@x.x.x: +``` + +* ``: the {% data variables.product.prodname_codeql %} database to be analyzed. +* ``: the name of the {% data variables.product.prodname_dotcom %} organization that the pack is published to. +* ``: the name for the pack that you are using. +* `@x.x.x`: an optional version number. If omitted, the latest version will be used. +* `:`: an optional path to a query, directory, or query suite. If omitted, the pack’s default query suite will be used. + +The `analyze` command will run the default suite of any specified {% data variables.product.prodname_codeql %} packs. You can specify multiple {% data variables.product.prodname_codeql %} packs to be used for analyzing a {% data variables.product.prodname_codeql %} database. For example: + +```shell +codeql analyze / / +``` + +> [!NOTE] +> The `codeql pack download` command stores the pack it downloads in an internal location that is not intended for local modification. Unexpected (and hard to troubleshoot) behavior may result if the pack is modified after downloading. For more information about customizing packs, see [AUTOTITLE](/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/creating-and-working-with-codeql-packs). diff --git a/content/code-security/how-tos/scan-code-for-vulnerabilities/scan-from-the-command-line/writing-and-sharing-custom-queries-for-the-codeql-cli.md b/content/code-security/how-tos/scan-code-for-vulnerabilities/scan-from-the-command-line/write-custom-queries.md similarity index 73% rename from content/code-security/how-tos/scan-code-for-vulnerabilities/scan-from-the-command-line/writing-and-sharing-custom-queries-for-the-codeql-cli.md rename to content/code-security/how-tos/scan-code-for-vulnerabilities/scan-from-the-command-line/write-custom-queries.md index 085dc94f918c..8455c25667bb 100644 --- a/content/code-security/how-tos/scan-code-for-vulnerabilities/scan-from-the-command-line/writing-and-sharing-custom-queries-for-the-codeql-cli.md +++ b/content/code-security/how-tos/scan-code-for-vulnerabilities/scan-from-the-command-line/write-custom-queries.md @@ -1,6 +1,6 @@ --- -title: Writing and sharing custom queries for the CodeQL CLI -shortTitle: Write and share queries +title: Writing custom queries for the CodeQL CLI +shortTitle: Write custom queries intro: You can write your own {% data variables.product.prodname_codeql %} queries to find specific vulnerabilities and errors. product: '{% data reusables.gated-features.codeql %}' allowTitleToDifferFromFilename: true @@ -16,6 +16,7 @@ redirect_from: - /code-security/codeql-cli/using-custom-queries-with-the-codeql-cli - /code-security/codeql-cli/using-the-codeql-cli/using-custom-queries-with-the-codeql-cli - /code-security/how-tos/scan-code-for-vulnerabilities/scan-from-the-command-line/using-custom-queries-with-the-codeql-cli + - /code-security/how-tos/scan-code-for-vulnerabilities/scan-from-the-command-line/writing-and-sharing-custom-queries-for-the-codeql-cli contentType: how-tos --- @@ -35,21 +36,6 @@ When running queries with the `database analyze` command, you must include the f For more information about these metadata properties, see [Metadata for {% data variables.product.prodname_codeql %} queries](https://codeql.github.com/docs/writing-codeql-queries/metadata-for-codeql-queries/#metadata-for-codeql-queries) and the [Query metadata style guide](https://github.com/github/codeql/blob/main/docs/query-metadata-style-guide.md). -## Packaging custom queries - -When you write queries to share with others, save them in a custom {% data variables.product.prodname_codeql %} pack. - -To package your custom queries: - -1. Create a {% data variables.product.prodname_codeql %} pack with a `qlpack.yml` file in the root directory. -1. Save your custom queries (`.ql` files) in the pack root or its subdirectories. -1. Configure the `qlpack.yml` file to specify: - * How to compile the queries - * Dependencies on other {% data variables.product.prodname_codeql %} packs and libraries - * Query suite definitions - For more information about `qlpack.yml` properties, see [AUTOTITLE](/code-security/codeql-cli/getting-started-with-the-codeql-cli/customizing-analysis-with-codeql-packs#codeqlpack-yml-properties). -1. Publish your pack to {% data variables.product.prodname_registry %} - the {% data variables.product.prodname_dotcom %} {% data variables.product.prodname_container_registry %}. For more information, see [AUTOTITLE](/code-security/codeql-cli/getting-started-with-the-codeql-cli/customizing-analysis-with-codeql-packs). - ## Including query help for custom {% data variables.product.prodname_codeql %} queries in SARIF files For information about query help and documentation formats, see [AUTOTITLE](/code-security/concepts/code-scanning/codeql/custom-codeql-queries#query-documentation). @@ -69,6 +55,6 @@ To include query help in SARIF files when running code scanning analyses: > The `--sarif-add-query-help` option is available from {% data variables.product.prodname_codeql_cli %} v2.7.1 onwards. 1. Upload the SARIF file to {% data variables.product.github %}. -## Further reading +## Next steps -* [{% data variables.product.prodname_codeql %} queries](https://codeql.github.com/docs/writing-codeql-queries/codeql-queries/#codeql-queries) +To share and use your custom queries, see [AUTOTITLE](/code-security/how-tos/scan-code-for-vulnerabilities/scan-from-the-command-line/publish-and-use-packs). diff --git a/content/code-security/tutorials/customize-code-scanning/publishing-and-using-codeql-packs.md b/content/code-security/reference/code-scanning/codeql/codeql-cli/codeql-query-packs.md similarity index 54% rename from content/code-security/tutorials/customize-code-scanning/publishing-and-using-codeql-packs.md rename to content/code-security/reference/code-scanning/codeql/codeql-cli/codeql-query-packs.md index c356ed620f3a..8f4aa5ff0d59 100644 --- a/content/code-security/tutorials/customize-code-scanning/publishing-and-using-codeql-packs.md +++ b/content/code-security/reference/code-scanning/codeql/codeql-cli/codeql-query-packs.md @@ -1,6 +1,7 @@ --- -title: Publishing and using CodeQL packs -intro: You can publish your own {% data variables.product.prodname_codeql %} packs and use packs published by other people. +title: CodeQL query packs reference +shortTitle: CodeQL query packs +intro: Understand the compatibility, contents, and structure of {% data variables.product.prodname_codeql %} packs. product: '{% data reusables.gated-features.codeql %}' versions: fpt: '*' @@ -10,195 +11,38 @@ topics: - Code Security - Code scanning - CodeQL -redirect_from: - - /code-security/codeql-cli/publishing-and-using-codeql-packs - - /code-security/codeql-cli/using-the-codeql-cli/publishing-and-using-codeql-packs - - /code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/publishing-and-using-codeql-packs -contentType: tutorials + - Repositories + - Integration + - CI +contentType: reference --- -{% ifversion ghec or ghes %} +## {% data variables.product.prodname_codeql %} pack compatibility -## Working with {% data variables.product.prodname_codeql %} packs on {% data variables.enterprise.gh_enterprise %} +When a query pack is published, it includes pre-compiled representations of all the queries in it to increase analysis speed. However, if the version of {% data variables.product.prodname_codeql %} that performs the analysis is over 6 months newer than the the version that ran `codeql pack publish`, it may be necessary to compile the queries from source during analysis, slowing the process significantly. -By default, the {% data variables.product.prodname_codeql_cli %} expects to download {% data variables.product.prodname_codeql %} packs from and publish packs to the {% data variables.product.prodname_container_registry %} on {% data variables.product.prodname_dotcom_the_website %}. However, you can also work with {% data variables.product.prodname_codeql %} packs in a {% data variables.product.prodname_container_registry %} on {% data variables.enterprise.gh_enterprise %} by creating a `qlconfig.yml` file to tell the CLI which {% data variables.product.prodname_container_registry %} to use for each pack. +A pack published by the _latest_ public release of {% data variables.product.prodname_codeql %} will be useable by the version of {% data variables.product.prodname_codeql %} that is used by {% data variables.product.prodname_code_scanning %} and {% data variables.product.prodname_actions %}, even though that is often a slightly older release. -Create a `~/.codeql/qlconfig.yml` file on Linux/MacOS or `%HOMEPATH%\.codeql\qlconfig.yml` on Windows using your preferred text editor, and add entries to specify which registry to use for one or more package name patterns. -For example, the following `qlconfig.yml` file associates all packs with the {% data variables.product.prodname_container_registry %} at `{% data variables.enterprise.gh_enterprise_domain %}`, except packs matching `codeql/\*` or the `other-org/*` organization, which are associated with the {% data variables.product.prodname_container_registry %} on {% data variables.product.prodname_dotcom_the_website %}: - -```yaml -registries: -- packages: - - 'codeql/*' - - 'other-org/*' - # {% data variables.product.prodname_container_registry %} on {% data variables.product.prodname_dotcom_the_website %} - url: https://ghcr.io/v2/ -- packages: '*' - # {% data variables.product.prodname_container_registry %} hosted at `{% data variables.enterprise.gh_enterprise_domain %}` - url: {% data variables.enterprise.gh_enterprise_container_registry %} -``` - -The {% data variables.product.prodname_codeql_cli %} will determine which registry to use for a given package name by finding the first item in the `registries` list with a `packages` property that matches that package name. -This means that you’ll generally want to define the most specific package name patterns first. The `packages` property may be a single package name, a glob pattern, or a YAML list of package names and glob patterns. - -The `registries` list can also be placed inside a `codeql-workspace.yml` file. Doing so will allow you to define the registries to be used within a specific workspace, so that it can be shared amongst other {% data variables.product.prodname_codeql %} users of the workspace. The `registries` list in `codeql-workspace.yml` will be merged with and take precedence over the list in the global `qlconfig.yml`. For more information about `codeql-workspace.yml`, see [AUTOTITLE](/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/about-codeql-workspaces#about-codeql-workspaces). - -You can now use `codeql pack publish`, `codeql pack download`, and `codeql database analyze` to manage packs on {% data variables.enterprise.gh_enterprise %}. - -{% endif %} - -## Authenticating to {% data variables.product.github %} {% data variables.product.prodname_container_registries %} - -You can publish packs and download private packs by authenticating to the appropriate {% data variables.product.github %} {% data variables.product.prodname_container_registry %}. - -{% ifversion ghec or ghes %} - -### Authenticating to {% data variables.product.prodname_container_registries %} on {% data variables.product.prodname_dotcom_the_website %} - -{% endif %} - -You can authenticate to the {% data variables.product.prodname_container_registry %} in two ways: - -1. Pass the `--github-auth-stdin` option to the {% data variables.product.prodname_codeql_cli %}, then supply a {% data variables.product.prodname_github_apps %} token or {% data variables.product.pat_generic %} via standard input. -1. Set the `GITHUB_TOKEN` environment variable to a {% data variables.product.prodname_github_apps %} token or {% data variables.product.pat_generic %}. - -{% ifversion ghec or ghes %} - -### Authenticating to {% data variables.product.prodname_container_registries %} on {% data variables.enterprise.gh_enterprise %} - -Similarly, you can authenticate to a {% data variables.product.prodname_container_registry %} on {% data variables.enterprise.gh_enterprise %}, or authenticate to multiple registries simultaneously (for example, to download or run private packs from multiple registries) in two ways: - -1. Pass the `--registries-auth-stdin` option to the {% data variables.product.prodname_codeql_cli %}, then supply a registry authentication string via standard input. -1. Set the `CODEQL_REGISTRIES_AUTH` environment variable to a registry authentication string. - -A registry authentication string is a comma-separated list of `=` pairs, where `registry-url` is a {% data variables.product.prodname_container_registry %} URL, such as `{% data variables.enterprise.gh_enterprise_container_registry %}`, and `token` is a {% data variables.product.prodname_github_apps %} token or {% data variables.product.pat_generic %} for that {% data variables.product.prodname_container_registry %}. -This ensures that each token is only passed to the {% data variables.product.prodname_container_registry %} you specify. - -For example, the following registry authentication string specifies that the {% data variables.product.prodname_codeql_cli %} should authenticate as follows: - -* Use the token `` to authenticate to {% data variables.product.prodname_container_registry %} on {% data variables.product.prodname_dotcom_the_website %}. -* Use the token `` to authenticate to the {% data variables.product.prodname_container_registry %} for the enterprise at `{% data variables.enterprise.gh_enterprise_container_registry %}`. - -```shell -https://ghcr.io/v2/=,{% data variables.enterprise.gh_enterprise_container_registry %}= -``` - -{% endif %} - -## Configuring the `qlpack.yml` file before publishing - -{% data reusables.code-scanning.codeql-cli-version-ghes %} - -You can check and modify the configuration details of your {% data variables.product.prodname_codeql %} pack prior to publishing. Open the `qlpack.yml` file in your preferred text editor. - -```yaml -library: # set to true if the pack is a library. Set to false or omit for a query pack -name: / -version: -description: -defaultSuite: # optional, one or more queries in the pack to run by default - - query: /query-file>.ql -defaultSuiteFile: default-queries.qls # optional, a pointer to a query-suite in this pack -license: # optional, the license under which the pack is published -dependencies: # map from CodeQL pack name to version range -``` - -* `name:` must follow the `/` format, where `` is the {% data variables.product.prodname_dotcom %} organization that you will publish to and `` is the name for the pack. - -* A maximum of one of `defaultSuite` or `defaultSuiteFile` is allowed. These are two different ways to define a default query suite to be run, the first by specifying queries directly in the qlpack.yml file and the second by specifying a query suite in the pack. - -## Running `codeql pack publish` - -When you are ready to publish a pack to the {% data variables.product.prodname_dotcom %} {% data variables.product.prodname_container_registry %}, you can run the following command in the root of the pack directory: - -```shell -codeql pack publish -``` - -The published package will be displayed in the packages section of {% data variables.product.prodname_dotcom %} organization specified by the scope in the `qlpack.yml` file. - -> [!NOTE] -> If you're publishing model packs to the {% data variables.product.prodname_dotcom %} {% data variables.product.prodname_container_registry %} in order to extend coverage to all repositories in an organization as part of a default setup configuration, then you need to ensure that repositories running code scanning can access those model packs. For more information, see [AUTOTITLE](/code-security/code-scanning/managing-your-code-scanning-configuration/editing-your-configuration-of-default-setup) and [AUTOTITLE](/packages/learn-github-packages/configuring-a-packages-access-control-and-visibility). - -## Running `codeql pack download /` - -To run a pack that someone else has created, you must first download it by running the following command: - -```shell -codeql pack download /@x.x.x -``` - -* ``: the name of the {% data variables.product.prodname_dotcom %} organization that you will download from. -* ``: the name for the pack that you want to download. -* `@x.x.x`: an optional version number. If omitted, the latest version will be downloaded. - -This command accepts arguments for multiple packs. - -If you write scripts that specify a particular version number of a -query pack to download, keep in mind that when you update your version of -{% data variables.product.prodname_codeql %} to a newer one, you may -also need to switch to a newer version of the query pack. Newer -versions of {% data variables.product.prodname_codeql %} _may_ provide -degraded performance when used with query packs that have been pinned -to a very old version. For more information, see [About {% data variables.product.prodname_codeql %} -pack compatibility](#about-codeql-pack-compatibility). - -## Using a {% data variables.product.prodname_codeql %} pack to analyze a {% data variables.product.prodname_codeql %} database - -To analyze a {% data variables.product.prodname_codeql %} database with a {% data variables.product.prodname_codeql %} pack, run the following command: - -```shell -codeql database analyze /@x.x.x: -``` - -* ``: the {% data variables.product.prodname_codeql %} database to be analyzed. -* ``: the name of the {% data variables.product.prodname_dotcom %} organization that the pack is published to. -* ``: the name for the pack that you are using. -* `@x.x.x`: an optional version number. If omitted, the latest version will be used. -* `:`: an optional path to a query, directory, or query suite. If omitted, the pack’s default query suite will be used. - -The `analyze` command will run the default suite of any specified {% data variables.product.prodname_codeql %} packs. You can specify multiple {% data variables.product.prodname_codeql %} packs to be used for analyzing a {% data variables.product.prodname_codeql %} database. For example: - -```shell -codeql analyze / / -``` - -> [!NOTE] -> The `codeql pack download` command stores the pack it downloads in an internal location that is not intended for local modification. Unexpected (and hard to troubleshoot) behavior may result if the pack is modified after downloading. For more information about customizing packs, see [AUTOTITLE](/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/creating-and-working-with-codeql-packs). - -## About {% data variables.product.prodname_codeql %} pack compatibility - -When a query pack is published, it includes pre-compiled representations of all the queries in it. These pre-compiled queries are generally much faster to execute than it is to compile the QL source from scratch during the analysis. However, the pre-compiled queries also depend on certain internals of the QL evaluator, so if the version of {% data variables.product.prodname_codeql %} that performs the analysis is too different from the version that ran `codeql pack publish`, it may be necessary to compile the queries from source instead during analysis. The recompilation happens automatically and will not affect the _results_ of the analysis, but it can make the -analysis significantly slower. - -It can generally be assumed that if a pack is published with one release of {% data variables.product.prodname_codeql %}, the precompiled queries in it can be used directly by _later_ releases of {% data variables.product.prodname_codeql %}, as long as there is no more than 6 months between the release dates. We will make reasonable efforts to keep new releases compatible for longer than that, but make no promises. - -It can also be assumed that a pack published by the _latest_ public release of {% data variables.product.prodname_codeql %} will be useable by the version of {% data variables.product.prodname_codeql %} that is used by {% data variables.product.prodname_code_scanning %} and {% data variables.product.prodname_actions %}, even though that is often a slightly older release. - -As a user of a published query pack, you can check that the {% data variables.product.prodname_codeql %} makes use of the precompiled queries in it by inspecting the terminal output from an analysis runs that uses the query pack. If it contains lines looking like the following, then the precompiled queries were used successfully: +If your analysis contains lines like the following, then {% data variables.product.prodname_codeql %} is successfully using precompiled queries: ```shell [42/108] Loaded /long/path/to/query/Filename.qlx. ``` -However, if they instead look like the following, then usage of the precompiled queries failed: +If your analysis instead contains lines that look like the following, then {% data variables.product.prodname_codeql %} manually recompiled the queries from source: ```shell Compiling query plan for /long/path/to/query/Filename.ql. [42/108 comp 25s] Compiled /long/path/to/query/Filename.ql. ``` -The results of the analysis will still be good in this case, but to get optimal performance you may need to upgrade to a newer version of the {% data variables.product.prodname_codeql_cli %} and/or of the query pack. - -If you publish query packs on the {% data variables.product.prodname_container_registry %} on {% data variables.product.prodname_dotcom_the_website %} for others to use, we recommend that you use a recent release of {% data variables.product.prodname_codeql %} to run `codeql pack publish`, and that you publish a fresh version of your pack with an updated {% data variables.product.prodname_codeql %} version before the version you used turns 6 months old. That way you can ensure that users of your pack who keep _their_ {% data variables.product.prodname_codeql %} up to date will benefit from the pre-compiled queries in your pack. +To help users of your query pack benefit from pre-compiled queries, we recommend using a recent release of {% data variables.product.prodname_codeql %} to publish your packs. Additionally, you should publish a fresh version of your pack with an updated {% data variables.product.prodname_codeql %} version every 6 months. -If you publish query packs with the intention of using them on a {% data variables.product.prodname_ghe_server %} installation that uses its bundled {% data variables.product.prodname_codeql %} binaries, use the same {% data variables.product.prodname_codeql %} version to run `codeql pack publish`. Newer versions might produce pre-compiled queries that the one in {% data variables.product.prodname_ghe_server %} may not recognize. Your {% data variables.product.prodname_ghe_server %} administrator may choose to upgrade to a newer version of {% data variables.product.prodname_codeql %} periodically. If so, follow their lead. +If you publish query packs with the intention of using them on a {% data variables.product.prodname_ghe_server %} installation that uses its bundled {% data variables.product.prodname_codeql %} binaries, use the same {% data variables.product.prodname_codeql %} version to run `codeql pack publish`. -## About `qlpack.yml` files +## `qlpack.yml` files -When executing query-related commands, {% data variables.product.prodname_codeql %} first looks in siblings of the installation directory (and their subdirectories) for `qlpack.yml` files. -Then it checks the package cache for {% data variables.product.prodname_codeql %} packs which have been downloaded. This means that when you are developing queries locally, the local packages -in the installation directory override packages of the same name in the package cache, so that you can test your local changes. +When executing query-related commands, {% data variables.product.prodname_codeql %} first looks in siblings of the installation directory (and their subdirectories) for `qlpack.yml` files, then checks the package cache for downloaded {% data variables.product.prodname_codeql %} packs. This means that when your local packages in the installation directory override packages of the same name in the package cache, so you can test your local changes. The metadata in each `qlpack.yml` file tells {% data variables.product.prodname_codeql %} how to compile any queries in the pack, what libraries the pack depends on, and where to find query suite definitions. @@ -388,7 +232,7 @@ The following properties are supported in `qlpack.yml` files. warnOnImplicitThis: true ``` -## About `codeql-pack.lock.yml` files +## `codeql-pack.lock.yml` files `codeql-pack.lock.yml` files store the versions of the resolved transitive dependencies of a {% data variables.product.prodname_codeql %} pack. This file is created by the `codeql pack install` command if it does not already exist and should be added to your version control system. The `dependencies` section of the `qlpack.yml` file contains version ranges that are compatible with the pack. The `codeql-pack.lock.yml` file locks the versions to precise dependencies. This ensures that running `codeql pack install` on this the pack will always retrieve the same versions of dependencies even if newer compatible versions exist. @@ -417,9 +261,9 @@ The `codeql/cpp-all` dependency is locked to version 0.1.4. The `my-user/my-lib` In most cases, the `codeql-pack.lock.yml` file is only relevant for query packs since library packs are non-executable and usually do not need their transitive dependencies to be fixed. The exception to this is for library packs that contain tests. In this case, the `codeql-pack.lock.yml` file is used to ensure that the tests are always run with the same versions of dependencies to avoid spurious failures when there are mismatched dependencies. -## Examples of custom {% data variables.product.prodname_codeql %} packs +## Example custom {% data variables.product.prodname_codeql %} packs -When you write custom queries or tests, you should save them in custom {% data variables.product.prodname_codeql %} packs. For simplicity, try to organize each pack logically. For more information, see [AUTOTITLE](/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/creating-and-working-with-codeql-packs#codeql-pack-structure). Save files for queries and tests in separate packs and, where possible, organize custom packs into specific folders for each target language. This is particularly useful if you intend to publish your {% data variables.product.prodname_codeql %} packs so they can be shared with others or used in code scanning. For more information, see [AUTOTITLE](/code-security/code-scanning/introduction-to-code-scanning/about-code-scanning-with-codeql). +You should save files for custom queries and tests in separate packs, and organize custom packs into specific folders for each target language. ### {% data variables.product.prodname_codeql %} packs for custom libraries @@ -461,7 +305,7 @@ databases. You may also wish to specify the `tests` property. For more information about running tests, see [AUTOTITLE](/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/testing-custom-queries). -## Examples of {% data variables.product.prodname_codeql %} packs in the {% data variables.product.prodname_codeql %} repository +## Example {% data variables.product.prodname_codeql %} packs in the {% data variables.product.prodname_codeql %} repository Each of the languages in the {% data variables.product.prodname_codeql %} repository has four main {% data variables.product.prodname_codeql %} packs: diff --git a/content/code-security/reference/code-scanning/codeql/codeql-cli/index.md b/content/code-security/reference/code-scanning/codeql/codeql-cli/index.md index a16ddd036fe1..84b9210210c9 100644 --- a/content/code-security/reference/code-scanning/codeql/codeql-cli/index.md +++ b/content/code-security/reference/code-scanning/codeql/codeql-cli/index.md @@ -14,6 +14,7 @@ topics: children: - /sarif-output - /csv-output + - /codeql-query-packs - /extractor-options - /exit-codes redirect_from: diff --git a/content/code-security/reference/code-scanning/codeql/codeql-queries/index.md b/content/code-security/reference/code-scanning/codeql/codeql-queries/index.md index 097e3814c552..6c3865c30d5a 100644 --- a/content/code-security/reference/code-scanning/codeql/codeql-queries/index.md +++ b/content/code-security/reference/code-scanning/codeql/codeql-queries/index.md @@ -1,6 +1,6 @@ --- title: Queries for CodeQL analysis -shortTitle: CodeQL queries +shortTitle: Built-in CodeQL queries intro: Explore the CodeQL queries that code scanning uses to analyze code. product: '{% data reusables.gated-features.code-scanning %}' versions: @@ -27,4 +27,3 @@ redirect_from: - /code-security/code-scanning/reference/code-ql-built-in-queries contentType: reference --- - diff --git a/content/code-security/tutorials/customize-code-scanning/index.md b/content/code-security/tutorials/customize-code-scanning/index.md index 6722ded6be18..be7820621aaf 100644 --- a/content/code-security/tutorials/customize-code-scanning/index.md +++ b/content/code-security/tutorials/customize-code-scanning/index.md @@ -21,6 +21,5 @@ children: - /customizing-analysis-with-codeql-packs - /creating-codeql-query-suites - /creating-and-working-with-codeql-packs - - /publishing-and-using-codeql-packs --- From e17d5e14fc97ffe6abd3fee4ae6cc64fc9ddbab3 Mon Sep 17 00:00:00 2001 From: docs-bot <77750099+docs-bot@users.noreply.github.com> Date: Fri, 6 Mar 2026 08:45:36 -0800 Subject: [PATCH 2/4] GraphQL schema update (#60087) Co-authored-by: github-merge-queue <118344674+github-merge-queue@users.noreply.github.com> --- src/graphql/data/fpt/schema.docs.graphql | 2 +- src/graphql/data/fpt/schema.json | 2 +- src/graphql/data/ghec/schema.docs.graphql | 2 +- src/graphql/data/ghec/schema.json | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/src/graphql/data/fpt/schema.docs.graphql b/src/graphql/data/fpt/schema.docs.graphql index c808c07f1490..acf6608c6027 100644 --- a/src/graphql/data/fpt/schema.docs.graphql +++ b/src/graphql/data/fpt/schema.docs.graphql @@ -50807,7 +50807,7 @@ type Repository implements Node & PackageOwner & ProjectOwner & ProjectV2Recent isArchived: Boolean! """ - Returns true if blank issue creation is allowed + Returns true if the viewer can create a blank issue in this repository """ isBlankIssuesEnabled: Boolean! diff --git a/src/graphql/data/fpt/schema.json b/src/graphql/data/fpt/schema.json index a92542c5bf07..f234693332bb 100644 --- a/src/graphql/data/fpt/schema.json +++ b/src/graphql/data/fpt/schema.json @@ -66430,7 +66430,7 @@ }, { "name": "isBlankIssuesEnabled", - "description": "

Returns true if blank issue creation is allowed.

", + "description": "

Returns true if the viewer can create a blank issue in this repository.

", "type": "Boolean!", "id": "boolean", "kind": "scalars", diff --git a/src/graphql/data/ghec/schema.docs.graphql b/src/graphql/data/ghec/schema.docs.graphql index c808c07f1490..acf6608c6027 100644 --- a/src/graphql/data/ghec/schema.docs.graphql +++ b/src/graphql/data/ghec/schema.docs.graphql @@ -50807,7 +50807,7 @@ type Repository implements Node & PackageOwner & ProjectOwner & ProjectV2Recent isArchived: Boolean! """ - Returns true if blank issue creation is allowed + Returns true if the viewer can create a blank issue in this repository """ isBlankIssuesEnabled: Boolean! diff --git a/src/graphql/data/ghec/schema.json b/src/graphql/data/ghec/schema.json index a92542c5bf07..f234693332bb 100644 --- a/src/graphql/data/ghec/schema.json +++ b/src/graphql/data/ghec/schema.json @@ -66430,7 +66430,7 @@ }, { "name": "isBlankIssuesEnabled", - "description": "

Returns true if blank issue creation is allowed.

", + "description": "

Returns true if the viewer can create a blank issue in this repository.

", "type": "Boolean!", "id": "boolean", "kind": "scalars", From 19064e30aa9d918235481316e0347523d8797f75 Mon Sep 17 00:00:00 2001 From: John Clement <70238417+jclement136@users.noreply.github.com> Date: Fri, 6 Mar 2026 12:00:06 -0500 Subject: [PATCH 3/4] Revisit organization-level roles docs (#60004) --- .../index.md | 3 +- ...rmissions-of-custom-organization-roles.md} | 13 +- ...ssions-of-predefined-organization-roles.md | 210 ++++++++++++++++++ .../roles-in-an-organization.md | 204 +++-------------- .../using-organization-roles.md | 4 - .../pre-defined-organization-roles.md | 16 -- 6 files changed, 250 insertions(+), 200 deletions(-) rename content/organizations/managing-peoples-access-to-your-organization-with-roles/{about-custom-organization-roles.md => permissions-of-custom-organization-roles.md} (97%) create mode 100644 content/organizations/managing-peoples-access-to-your-organization-with-roles/permissions-of-predefined-organization-roles.md delete mode 100644 data/reusables/organizations/pre-defined-organization-roles.md diff --git a/content/organizations/managing-peoples-access-to-your-organization-with-roles/index.md b/content/organizations/managing-peoples-access-to-your-organization-with-roles/index.md index 18394ce7c7e7..fa91047aca83 100644 --- a/content/organizations/managing-peoples-access-to-your-organization-with-roles/index.md +++ b/content/organizations/managing-peoples-access-to-your-organization-with-roles/index.md @@ -12,7 +12,8 @@ versions: children: - /roles-in-an-organization - /using-organization-roles - - /about-custom-organization-roles + - /permissions-of-custom-organization-roles + - /permissions-of-predefined-organization-roles - /managing-custom-organization-roles - /maintaining-ownership-continuity-for-your-organization - /adding-a-billing-manager-to-your-organization diff --git a/content/organizations/managing-peoples-access-to-your-organization-with-roles/about-custom-organization-roles.md b/content/organizations/managing-peoples-access-to-your-organization-with-roles/permissions-of-custom-organization-roles.md similarity index 97% rename from content/organizations/managing-peoples-access-to-your-organization-with-roles/about-custom-organization-roles.md rename to content/organizations/managing-peoples-access-to-your-organization-with-roles/permissions-of-custom-organization-roles.md index f2ea78179897..0c15a26b07a8 100644 --- a/content/organizations/managing-peoples-access-to-your-organization-with-roles/about-custom-organization-roles.md +++ b/content/organizations/managing-peoples-access-to-your-organization-with-roles/permissions-of-custom-organization-roles.md @@ -1,9 +1,14 @@ --- -title: About custom organization roles +title: Permissions of custom organization roles intro: "You can control access to your {% ifversion org-custom-role-with-repo-permissions %}organization's settings and repositories{% else %}organization's settings{% endif %} with custom organization roles." +redirect_from: + - /organizations/managing-peoples-access-to-your-organization-with-roles/about-custom-organization-roles versions: feature: 'custom-org-roles' -shortTitle: Custom organization roles +topics: + - Organizations +shortTitle: Custom roles permissions + product: 'Organizations on {% data variables.product.prodname_ghe_cloud %}{% ifversion ghes %} and {% data variables.product.prodname_ghe_server %}{% endif %}' --- @@ -13,6 +18,8 @@ You can create and assign custom organization roles in your organization's setti {% ifversion org-custom-role-with-repo-permissions %} +## Combining organization and repository permissions + You can also create a custom organization role that includes permissions for repositories. Repository permissions grant access to all current and future repositories in the organization. There are several ways to combine permissions for repositories and organizations. @@ -109,4 +116,4 @@ You can only choose an additional permission if it's not already included in the {% data reusables.organizations.precedence-for-different-levels %} -{% endif %} +{% endif %} \ No newline at end of file diff --git a/content/organizations/managing-peoples-access-to-your-organization-with-roles/permissions-of-predefined-organization-roles.md b/content/organizations/managing-peoples-access-to-your-organization-with-roles/permissions-of-predefined-organization-roles.md new file mode 100644 index 000000000000..4aec5d077937 --- /dev/null +++ b/content/organizations/managing-peoples-access-to-your-organization-with-roles/permissions-of-predefined-organization-roles.md @@ -0,0 +1,210 @@ +--- +title: Permissions of predefined organization roles +intro: "Learn about the predefined organization roles and the permissions each role grants in your organization." +versions: + feature: 'org-pre-defined-roles' +topics: + - Organizations +shortTitle: Predefined roles permissions +product: 'Organizations on {% data variables.product.prodname_ghe_cloud %}{% ifversion ghes %} and {% data variables.product.prodname_ghe_server %}{% endif %}' +--- + +Organizations support several predefined roles for managing your organization members' access to resources. Assigning predefined roles is the fastest way to assign the permissions someone needs for their responsibilities. + +## About predefined organization roles + +Predefined organization roles are roles that are available by default in every organization. You don't need to create them yourself. They can include both organization permissions that let the recipient manage the organization, as well as repository permissions that apply to all of the repositories in the organization. The following predefined roles are built into every organization based on common patterns of permissions organizations usually need. + +The predefined roles for organization access are: + +* **Member:** Grants standard access to organization features. +{%- ifversion fpt or ghec %} +* **Moderator:** Grants additional permissions to help moderate organization-level discussions and community content. +{%- endif %} +* **Owner:** Grants full administrative control of the organization. +{%- ifversion fpt or ghec %} +* **Billing manager:** Grants permission to view and manage billing settings and subscription details for the organization. +{%- endif %} +{%- ifversion fpt or ghec or ghes > 3.15 %} +* **Security manager:** Grants the ability to manage security policies, security alerts, and security configurations for an organization and all its repositories. +* **CI/CD admin:** Grants admin access to manage Actions policies, runners, runner groups, hosted compute network configurations, secrets, variables, and usage metrics for an organization. +{%- endif %} +{%- ifversion org-app-manager-teams %} +* **App Manager:** Grants the ability to create, edit, and delete all GitHub Apps in an organization. +{%- endif %} + +There are also roles that grant access to repositories in the organization: + +* **All-repository read:** Grants read access to all repositories in the organization. +* **All-repository write:** Grants write access to all repositories in the organization. +* **All-repository triage:** Grants triage access to all repositories in the organization. +* **All-repository maintain:** Grants maintenance access to all repositories in the organization. +* **All-repository admin:** Grants admin access to all repositories in the organization. + +You choose between the owner and member roles when you invite or add someone to your organization. Other roles are assigned to existing people in your organization. + +You can also grant users custom permissions in addition to these predefined roles. See [AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/permissions-of-custom-organization-roles). + +## Permissions of predefined roles + +The following table summarizes which permissions are included with each predefined organization role. + +{% ifversion fpt or ghec %} + + +{% rowheaders %} + +| Organization permission | Owners | Members | Moderators | Billing managers | Security managers | +|:------------------------|:------:|:-------:|:----------:|:----------------:|:-----------------:| +| Create repositories (see [AUTOTITLE](/organizations/managing-organization-settings/restricting-repository-creation-in-your-organization)) | ✓ | ✓ | ✓ | ✗ | ✓ | +| View and edit billing information | ✓ | ✗ | ✗ | ✓ | ✗ | +| Invite people to join the organization | ✓ | ✗ | ✗ | ✗ | ✗ | +| Edit and cancel invitations to join the organization | ✓ | ✗ |✗ | ✗ | ✗ | +| Remove members from the organization | ✓ | ✗ | ✗ |✗ | ✗ | +| Reinstate former members to the organization | ✓ | ✗ | ✗ | ✗ | ✗ | +| Add and remove people from **all teams** | ✓ | ✗ | ✗ | ✗ | ✗ | +| Promote organization members to _team maintainer_ | ✓ | ✗ | ✗ | ✗ | ✗ | +| Configure code review assignments (see [AUTOTITLE](/organizations/organizing-members-into-teams/managing-code-review-settings-for-your-team)) | ✓ | ✗ | ✗ | ✗ | ✗ | +| Set scheduled reminders (see [AUTOTITLE](/organizations/organizing-members-into-teams/managing-scheduled-reminders-for-your-team)) | ✓ |✗ | ✗ | ✗ | ✗ | +| Add collaborators to **all repositories** | ✓ | ✗ | ✗ | ✗ | ✗ | +| Access the organization audit log | ✓ | ✗ | ✗ | ✗ | ✗ | +| Edit the organization's profile page (see [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-github-profile/customizing-your-profile/about-your-organizations-profile)) | ✓ | ✗ | ✗ | ✗ | ✗ | +| {% ifversion ghec %} | +| Verify the organization's domains (see [AUTOTITLE](/organizations/managing-organization-settings/verifying-or-approving-a-domain-for-your-organization)) | ✓ | ✗ |✗ | ✗ | ✗ | +| Restrict email notifications to verified or approved domains (see [AUTOTITLE](/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/restricting-email-notifications-for-your-organization)) | ✓ | ✗ | ✗ | ✗ | ✗ | +| {% endif %} | +| Delete **all teams** | ✓ | ✗ | ✗ | ✗ | ✗ | +| Delete the organization account, including all repositories | ✓ | ✗ | ✗ | ✗ | ✗ | +| Create teams (see [AUTOTITLE](/organizations/managing-organization-settings/setting-team-creation-permissions-in-your-organization)) | ✓ | ✓ | ✓ | ✗ | ✓ | +| [Move teams in an organization's hierarchy](/organizations/organizing-members-into-teams/moving-a-team-in-your-organizations-hierarchy) | ✓ | ✗ | ✗ | ✗ | ✗ | +| {% ifversion projects-v1 %} | +| Create projects (see [AUTOTITLE](/organizations/managing-access-to-your-organizations-project-boards/project-board-permissions-for-an-organization)) | ✓ | ✓ | ✓ | ✗ | ✓ | +| {% endif %} | +| See all organization members and teams | ✓ | ✓ | ✓ | ✗ | ✓ | +| @mention any visible team | ✓ | ✓ | ✓ | ✗ | ✓ | +| Can be made a _team maintainer_ | ✓ | ✓ | ✓ | ✗ | ✓ | +| {% ifversion ghec %} | +| View organization insights (see [AUTOTITLE](/organizations/collaborating-with-groups-in-organizations/viewing-insights-for-dependencies-in-your-organization)) | ✓ | ✓ | ✓ | ✗ | ✓ | +| {% endif %} | +| Hide comments on writable commits, pull requests, and issues (see [AUTOTITLE](/communities/moderating-comments-and-conversations/managing-disruptive-comments#hiding-a-comment)) | ✓ | ✓ | ✓ | ✗ | ✓ | +| Hide comments on _all_ commits, pull requests, and issues (see [AUTOTITLE](/communities/moderating-comments-and-conversations/managing-disruptive-comments#hiding-a-comment)) | ✓ | ✗ | ✓ | ✗ | ✓ | +| Block and unblock non-member contributors (see [AUTOTITLE](/communities/maintaining-your-safety-on-github/blocking-a-user-from-your-organization)) | ✓ | ✗ | ✓ | ✗ |✗ | +| Limit interactions for certain users in public repositories (see [AUTOTITLE](/communities/moderating-comments-and-conversations/limiting-interactions-in-your-organization)) | ✓ | ✗ | ✓ | ✗ | ✗ | +| {% ifversion ghec %} | +| Manage viewing of organization dependency insights (see [AUTOTITLE](/organizations/managing-organization-settings/changing-the-visibility-of-your-organizations-dependency-insights)) | ✓ | ✗ | ✗ | ✗ | ✗ | +| {% endif %} | +| Set a team profile picture in **all teams** (see [AUTOTITLE](/organizations/organizing-members-into-teams/setting-your-teams-profile-picture)) | ✓ | ✗ | ✗ | ✗ | ✗ | +| Sponsor accounts and manage the organization's sponsorships (see [AUTOTITLE](/sponsors/sponsoring-open-source-contributors)) | ✓ | ✗ | ✗ | ✓ | ✓ | +| Manage email updates from sponsored accounts (see [AUTOTITLE](/organizations/managing-organization-settings/managing-updates-from-accounts-your-organization-sponsors)) | ✓ | ✗ | ✗ | ✗ | ✗ | +| Attribute your sponsorships to another organization (see [AUTOTITLE](/sponsors/sponsoring-open-source-contributors/attributing-sponsorships-to-your-organization) for details ) | ✓ | ✗ | ✗ | ✗ | ✗ | +| Manage the publication of {% data variables.product.prodname_pages %} sites from repositories in the organization (see [AUTOTITLE](/organizations/managing-organization-settings/managing-the-publication-of-github-pages-sites-for-your-organization)) | ✓ | ✗ | ✗ | ✗ | ✗ | +| Manage security and analysis settings (see [AUTOTITLE](/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/managing-security-and-analysis-settings-for-your-organization)) | ✓ | ✗ | ✗ | ✗ | ✓ | +| View security overview for the organization (see [AUTOTITLE](/code-security/security-overview/about-security-overview)) | ✓ | ✗ | ✗ | ✗ | ✓ | +| {% ifversion ghec %} | +| Enable and enforce [SAML single sign-on](/organizations/managing-saml-single-sign-on-for-your-organization/about-identity-and-access-management-with-saml-single-sign-on) | ✓ | ✗ | ✗ | ✗ | ✗ | +| [Manage a user's SAML access to your organization](/organizations/granting-access-to-your-organization-with-saml-single-sign-on/viewing-and-managing-a-members-saml-access-to-your-organization) | ✓ | ✗ | ✗ | ✗ | ✗ | +| Manage an organization's SSH certificate authorities (see [AUTOTITLE](/organizations/managing-git-access-to-your-organizations-repositories/managing-your-organizations-ssh-certificate-authorities)) | ✓ | ✗ | ✗ | ✗ | ✗ | +| {% endif %} | +| Transfer repositories | ✓ | ✗ | ✗ | ✗ | ✗ | +| Purchase, install, manage billing for, and cancel {% data variables.product.prodname_marketplace %} apps | ✓ | ✗ | ✗ | ✗ | ✗ | +| List apps in {% data variables.product.prodname_marketplace %} | ✓ | ✗ | ✗ | ✗ | ✗ | +| Receive [{% data variables.product.prodname_dependabot_alerts %} about insecure dependencies](/code-security/dependabot/dependabot-alerts/about-dependabot-alerts) for all of an organization's repositories | ✓ | ✗ | ✗ | ✗ | ✓ | +| Manage {% data variables.product.prodname_dependabot_security_updates %} (see [AUTOTITLE](/code-security/dependabot/dependabot-security-updates/about-dependabot-security-updates)) | ✓ | ✗ | ✗ | ✗ | ✓ | +| [Manage the forking policy](/organizations/managing-organization-settings/managing-the-forking-policy-for-your-organization) | ✓ | ✗ | ✗ | ✗ | ✗ | +| [Limit activity in public repositories in an organization](/communities/moderating-comments-and-conversations/limiting-interactions-in-your-organization) | ✓ | ✗ | ✗ | ✗ | ✗ | +| Pull (read) _all repositories_ in the organization | ✓ | ✗ | ✗ | ✗ | ✓ | +| Push (write) and clone (copy) _all repositories_ in the organization | ✓ | ✗ | ✗ | ✗ | ✗ | +| Convert organization members to {% ifversion repository-collaborators %}[outside collaborators or repository collaborators](/organizations/managing-peoples-access-to-your-organization-with-roles/roles-in-an-organization#outside-collaborators-or-repository-collaborators){% else %}[outside collaborators](/organizations/managing-peoples-access-to-your-organization-with-roles/roles-in-an-organization#outside-collaborators){% endif %} | ✓ | ✗ | ✗ | ✗ | ✗ | +| [View people with access to an organization repository](/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/viewing-people-with-access-to-your-repository) | ✓ | ✗ | ✗ | ✗ | ✗ | +| {% ifversion ghec %} | +| [Export a list of people with access to an organization repository](/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/viewing-people-with-access-to-your-repository#exporting-a-list-of-people-with-access-to-your-repository) | ✓ | ✗ | ✗ | ✗ | ✗ | +| {% endif %} | +| Manage the default branch name (see [AUTOTITLE](/organizations/managing-organization-settings/managing-the-default-branch-name-for-repositories-in-your-organization)) | ✓ | ✗ | ✗ | ✗ | ✗ | +| Manage default labels (see [AUTOTITLE](/organizations/managing-organization-settings/managing-default-labels-for-repositories-in-your-organization)) | ✓ | ✗ | ✗ | ✗ | ✗ | +| {% ifversion ghec %} | +| Enable team synchronization (see [AUTOTITLE](/organizations/managing-saml-single-sign-on-for-your-organization/managing-team-synchronization-for-your-organization)) | ✓ | ✗ | ✗ | ✗ | ✗ | +| {% endif %} | +| Manage pull request reviews in the organization (see [AUTOTITLE](/organizations/managing-organization-settings/managing-pull-request-reviews-in-your-organization)) | ✓ | ✗ | ✗ | ✗ | ✗ | +| {% ifversion repo-rules-enterprise %} | +| Manage organization-level rulesets (see [AUTOTITLE](/organizations/managing-organization-settings/managing-rulesets-for-repositories-in-your-organization)) | ✓ | ✗ | ✗ | ✗ | ✗ | +| {% endif %} | +| {% ifversion push-protection-bypass-fine-grained-permissions %} | +| Review and manage {% data variables.product.prodname_secret_scanning %} bypass requests (see [AUTOTITLE](/code-security/secret-scanning/using-advanced-secret-scanning-and-push-protection-features/delegated-bypass-for-push-protection)) | ✓ | ✗ | ✗ | ✗ | ✓ | +| {% endif %} | +| {% ifversion security-delegated-alert-dismissal %} | +| Review and manage {% data variables.product.prodname_secret_scanning %} dismissal requests (see [AUTOTITLE](/code-security/secret-scanning/using-advanced-secret-scanning-and-push-protection-features/enabling-delegated-alert-dismissal-for-secret-scanning)) | ✓ | ✗ | ✗ | ✗ | ✓ | +| {% endif %} | +| {% ifversion security-delegated-alert-dismissal %} | +| Review and manage {% data variables.product.prodname_code_scanning %} dismissal requests (see [AUTOTITLE](/code-security/code-scanning/managing-your-code-scanning-configuration/enabling-delegated-alert-dismissal-for-code-scanning)) | ✓ | ✗ | ✗ | ✗ | ✓ | +| {% endif %} | +| {% ifversion dependabot-delegated-alert-dismissal %} | +| Review {% data variables.product.prodname_dependabot %} alert dismissal requests (see [AUTOTITLE](/code-security/dependabot/dependabot-alerts/enable-delegated-alert-dismissal)) | ✓ | ✗ | ✗ | ✗ | ✓ | +| Bypass {% data variables.product.prodname_dependabot %} alert dismissal requests (see [AUTOTITLE](/code-security/dependabot/dependabot-alerts/enable-delegated-alert-dismissal)) | ✓ | ✗ | ✗ | ✗ | ✓ | +| {% endif %} | + +{% endrowheaders %} + +{% elsif ghes %} + + +{% rowheaders %} + +| Organization action | Owners | Members | Security managers | +|:--------------------|:------:|:-------:|:-------:| +| Invite people to join the organization | ✓ | ✗ |✗ | +| Edit and cancel invitations to join the organization | ✓ | ✗ | ✗ | +| Remove members from the organization | ✓ | ✗ | ✗ | +| Reinstate former members to the organization | ✓ | ✗ | ✗ | +| Add and remove people from **all teams** | ✓ | ✗ | ✗ | +| Promote organization members to _team maintainer_ | ✓ | ✗ | ✗ | +| Configure code review assignments (see [AUTOTITLE](/organizations/organizing-members-into-teams/managing-code-review-settings-for-your-team)) | ✓ | ✗ | ✗ | +| Add collaborators to **all repositories** | ✓ | ✗ | ✗ | +| Access the organization audit log | ✓ | ✗ | ✗ | +| Edit the organization's profile page (see [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-github-profile/customizing-your-profile/about-your-organizations-profile)) | ✓ | ✗ | ✗ | +| Verify the organization's domains (see [AUTOTITLE](/organizations/managing-organization-settings/verifying-or-approving-a-domain-for-your-organization)) | ✓ | ✗ | ✗ | +| Restrict email notifications to verified or approved domains (see [AUTOTITLE](/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/restricting-email-notifications-for-your-organization)) | ✓ | ✗ | ✗ | +| Delete **all teams** | ✓ | ✗ | ✗ | +| Delete the organization account, including all repositories | ✓ | ✗ | ✗ | +| Create teams (see [AUTOTITLE](/organizations/managing-organization-settings/setting-team-creation-permissions-in-your-organization)) | ✓ | ✓ | ✓ | +| See all organization members and teams | ✓ | ✓ | ✓ | +| @mention any visible team | ✓ | ✓ | ✓ | +| Can be made a _team maintainer_ | ✓ | ✓ | ✓ | +| Transfer repositories | ✓ | ✗ | ✗ | +| Manage security and analysis settings (see [AUTOTITLE](/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/managing-security-and-analysis-settings-for-your-organization)) | ✓ | ✗ | ✓ | +| View the security overview for the organization (see [AUTOTITLE](/code-security/security-overview/about-the-security-overview)) | ✓ | ✗ | ✓ | +| {% ifversion security-delegated-alert-dismissal %} | +| Review and manage {% data variables.product.prodname_secret_scanning %} dismissal requests | ✓ | ✗ | ✓ | +| {% endif %} | +| {% ifversion security-delegated-alert-dismissal %} | +| Review and manage {% data variables.product.prodname_code_scanning %} dismissal requests | ✓ | ✗ | ✓ | +| {% endif %} | +| {% ifversion dependabot-delegated-alert-dismissal %} | +| Review {% data variables.product.prodname_dependabot %} alert dismissal requests | ✓ | ✗ | ✓ | +| Bypass {% data variables.product.prodname_dependabot %} alert dismissal requests | ✓ | ✗ | ✓ | +| {% endif %} | +| Manage {% data variables.product.prodname_dependabot_security_updates %} (see [AUTOTITLE](/code-security/dependabot/dependabot-security-updates/about-dependabot-security-updates)) | ✓ | ✗ | ✓ | +| Manage an organization's SSH certificate authorities (see [AUTOTITLE](/organizations/managing-git-access-to-your-organizations-repositories/managing-your-organizations-ssh-certificate-authorities)) | ✓ | ✗ | ✗ | +| {% ifversion projects-v1 %} | +| Create {% data variables.projects.projects_v1_boards %} (see [AUTOTITLE](/organizations/managing-access-to-your-organizations-project-boards/project-board-permissions-for-an-organization)) | ✓ | ✓ | ✓ | +| {% endif %} | +| Hide comments on commits, pull requests, and issues (see [AUTOTITLE](/communities/moderating-comments-and-conversations/managing-disruptive-comments#hiding-a-comment)) | ✓ | ✓ | ✓ | +| Set a team profile picture in **all teams** (see [AUTOTITLE](/organizations/organizing-members-into-teams/setting-your-teams-profile-picture)) | ✓ | ✗ | ✗ | +| Manage the publication of {% data variables.product.prodname_pages %} sites from repositories in the organization (see [AUTOTITLE](/organizations/managing-organization-settings/managing-the-publication-of-github-pages-sites-for-your-organization)) | ✓ | ✗ | ✗ | +| [Move teams in an organization's hierarchy](/organizations/organizing-members-into-teams/moving-a-team-in-your-organizations-hierarchy) | ✓ | ✗ | ✗ | +| Pull (read) _all repositories_ in the organization | ✓ | ✗ | ✓ | +| Push (write) and clone (copy) _all repositories_ in the organization | ✓ |✗ | ✗ | +| Convert organization members to {% ifversion repository-collaborators %}[outside collaborators or repository collaborators](/organizations/managing-peoples-access-to-your-organization-with-roles/roles-in-an-organization#outside-collaborators-or-repository-collaborators){% else %}[outside collaborators](/organizations/managing-peoples-access-to-your-organization-with-roles/roles-in-an-organization#outside-collaborators){% endif %} | ✓ | ✗ | ✗ | +| [View people with access to an organization repository](/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/viewing-people-with-access-to-your-repository) | ✓ | ✗ | ✗ | +| [Export a list of people with access to an organization repository](/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/viewing-people-with-access-to-your-repository#exporting-a-list-of-people-with-access-to-your-repository) | ✓ | ✗ | ✗ | +| Manage default labels (see [AUTOTITLE](/organizations/managing-organization-settings/managing-default-labels-for-repositories-in-your-organization)) | ✓ | ✗ | ✗ | +| {% ifversion pull-request-approval-limit %} | +| Manage pull request reviews in the organization (see [AUTOTITLE](/organizations/managing-organization-settings/managing-pull-request-reviews-in-your-organization)) | ✓ | ✗ | ✗ | +| {% endif %} | + +{% endrowheaders %} + +{% endif %} + +## Next steps + +* [AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/using-organization-roles) \ No newline at end of file diff --git a/content/organizations/managing-peoples-access-to-your-organization-with-roles/roles-in-an-organization.md b/content/organizations/managing-peoples-access-to-your-organization-with-roles/roles-in-an-organization.md index 568f98bc352d..9679a8dc872a 100644 --- a/content/organizations/managing-peoples-access-to-your-organization-with-roles/roles-in-an-organization.md +++ b/content/organizations/managing-peoples-access-to-your-organization-with-roles/roles-in-an-organization.md @@ -10,6 +10,9 @@ versions: fpt: '*' ghes: '*' ghec: '*' +topics: + - Organizations + - Teams shortTitle: Roles in an organization --- @@ -21,29 +24,41 @@ Repository-level roles give organization members, outside collaborators and team Team-level roles are roles that give permissions to manage a team. You can give any individual member of a team the team maintainer role, which gives the member a number of administrative permissions over a team. For more information, see [AUTOTITLE](/organizations/organizing-members-into-teams/assigning-the-team-maintainer-role-to-a-team-member). -Organization-level roles are sets of permissions that can be assigned to individuals or teams to manage an organization and the organization's repositories, teams, and settings. For more information about all the roles available at the organization level, see [About organization roles](#about-organization-roles). +{% ifversion org-pre-defined-roles %} +Organization-level roles are sets of permissions that can be assigned to individuals or teams to manage an organization and the organization's repositories, teams, and settings. For more information about all the roles available at the organization level, see [AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/permissions-of-predefined-organization-roles). +{% endif %} + +{% ifversion ghec or ghes %} +If your organization is owned by an enterprise account, enterprise owners can choose to join your organization with any role. For more information, see [AUTOTITLE](/admin/user-management/managing-organizations-in-your-enterprise/managing-your-role-in-an-organization-owned-by-your-enterprise). +{% endif %} {% ifversion org-pre-defined-roles %} -## About pre-defined organization roles +## About predefined organization roles -{% data reusables.organizations.pre-defined-organization-roles %} +Predefined organization roles are roles that are available by default in every organization. You don't need to create them yourself. They can include both organization permissions that let the recipient manage the organization, as well as repository permissions that apply to all of the repositories in the organization. -For more information, see [AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/using-organization-roles). +For more information, see [AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/permissions-of-predefined-organization-roles). {% endif %} -## About organization roles +## About custom organization roles -You can assign people to a variety of organization-level roles to control your members' access to your organization and its resources. For more details about the individual permissions included in each role, see [Permissions for organization roles](#permissions-for-organization-roles). +{% data reusables.organizations.custom-org-roles-intro %} -{% ifversion custom-org-roles %} -For more granular control of access to your organization's settings, you can create a custom organization role. For more information, see [AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/about-custom-organization-roles). +{% ifversion fpt %} +This feature is only available to organizations on {% data variables.product.prodname_ghe_cloud %}. +{% data reusables.enterprise.link-to-ghec-trial %} {% endif %} -{% ifversion ghec or ghes %} -If your organization is owned by an enterprise account, enterprise owners can choose to join your organization with any role. For more information, see [AUTOTITLE](/admin/user-management/managing-organizations-in-your-enterprise/managing-your-role-in-an-organization-owned-by-your-enterprise). -{% endif %} +For more information on the permissions available with custom roles, see [AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/permissions-of-custom-organization-roles). + + +## Descriptions of predefined organization roles + +You can assign people to a variety of organization-level roles to control your members' access to your organization and its resources. + +Upon invitation, you can add a user as an owner, billing manager, or member. After they have joined, you can designate them additional permissions under a predefined or custom role, such as a Moderator role or a CI/CD role. ### Organization owners @@ -108,169 +123,6 @@ To control who can add outside collaborators{% ifversion repository-collaborator * [AUTOTITLE](/admin/policies/enforcing-policies-for-your-enterprise/enforcing-repository-management-policies-in-your-enterprise#enforcing-a-policy-for-inviting-outside-collaborators-to-repositories) {% endif %} -## Permissions for organization roles - -{% ifversion fpt %} -Some of the features listed below are limited to organizations using {% data variables.product.prodname_ghe_cloud %}. {% data reusables.enterprise.link-to-ghec-trial %} -{% endif %} - -{% ifversion fpt or ghec %} - - -{% rowheaders %} - -| Organization permission | Owners | Members | Moderators | Billing managers | Security managers | -|:------------------------|:------:|:-------:|:----------:|:----------------:|:-----------------:| -| Create repositories (see [AUTOTITLE](/organizations/managing-organization-settings/restricting-repository-creation-in-your-organization)) | ✓ | ✓ | ✓ | ✗ | ✓ | -| View and edit billing information | ✓ | ✗ | ✗ | ✓ | ✗ | -| Invite people to join the organization | ✓ | ✗ | ✗ | ✗ | ✗ | -| Edit and cancel invitations to join the organization | ✓ | ✗ |✗ | ✗ | ✗ | -| Remove members from the organization | ✓ | ✗ | ✗ |✗ | ✗ | -| Reinstate former members to the organization | ✓ | ✗ | ✗ | ✗ | ✗ | -| Add and remove people from **all teams** | ✓ | ✗ | ✗ | ✗ | ✗ | -| Promote organization members to _team maintainer_ | ✓ | ✗ | ✗ | ✗ | ✗ | -| Configure code review assignments (see [AUTOTITLE](/organizations/organizing-members-into-teams/managing-code-review-settings-for-your-team)) | ✓ | ✗ | ✗ | ✗ | ✗ | -| Set scheduled reminders (see [AUTOTITLE](/organizations/organizing-members-into-teams/managing-scheduled-reminders-for-your-team)) | ✓ |✗ | ✗ | ✗ | ✗ | -| Add collaborators to **all repositories** | ✓ | ✗ | ✗ | ✗ | ✗ | -| Access the organization audit log | ✓ | ✗ | ✗ | ✗ | ✗ | -| Edit the organization's profile page (see [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-github-profile/customizing-your-profile/about-your-organizations-profile)) | ✓ | ✗ | ✗ | ✗ | ✗ | -| {% ifversion ghec %} | -| Verify the organization's domains (see [AUTOTITLE](/organizations/managing-organization-settings/verifying-or-approving-a-domain-for-your-organization)) | ✓ | ✗ |✗ | ✗ | ✗ | -| Restrict email notifications to verified or approved domains (see [AUTOTITLE](/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/restricting-email-notifications-for-your-organization)) | ✓ | ✗ | ✗ | ✗ | ✗ | -| {% endif %} | -| Delete **all teams** | ✓ | ✗ | ✗ | ✗ | ✗ | -| Delete the organization account, including all repositories | ✓ | ✗ | ✗ | ✗ | ✗ | -| Create teams (see [AUTOTITLE](/organizations/managing-organization-settings/setting-team-creation-permissions-in-your-organization)) | ✓ | ✓ | ✓ | ✗ | ✓ | -| [Move teams in an organization's hierarchy](/organizations/organizing-members-into-teams/moving-a-team-in-your-organizations-hierarchy) | ✓ | ✗ | ✗ | ✗ | ✗ | -| {% ifversion projects-v1 %} | -| Create projects (see [AUTOTITLE](/organizations/managing-access-to-your-organizations-project-boards/project-board-permissions-for-an-organization)) | ✓ | ✓ | ✓ | ✗ | ✓ | -| {% endif %} | -| See all organization members and teams | ✓ | ✓ | ✓ | ✗ | ✓ | -| @mention any visible team | ✓ | ✓ | ✓ | ✗ | ✓ | -| Can be made a _team maintainer_ | ✓ | ✓ | ✓ | ✗ | ✓ | -| {% ifversion ghec %} | -| View organization insights (see [AUTOTITLE](/organizations/collaborating-with-groups-in-organizations/viewing-insights-for-dependencies-in-your-organization)) | ✓ | ✓ | ✓ | ✗ | ✓ | -| {% endif %} | -| Hide comments on writable commits, pull requests, and issues (see [AUTOTITLE](/communities/moderating-comments-and-conversations/managing-disruptive-comments#hiding-a-comment)) | ✓ | ✓ | ✓ | ✗ | ✓ | -| Hide comments on _all_ commits, pull requests, and issues (see [AUTOTITLE](/communities/moderating-comments-and-conversations/managing-disruptive-comments#hiding-a-comment)) | ✓ | ✗ | ✓ | ✗ | ✓ | -| Block and unblock non-member contributors (see [AUTOTITLE](/communities/maintaining-your-safety-on-github/blocking-a-user-from-your-organization)) | ✓ | ✗ | ✓ | ✗ |✗ | -| Limit interactions for certain users in public repositories (see [AUTOTITLE](/communities/moderating-comments-and-conversations/limiting-interactions-in-your-organization)) | ✓ | ✗ | ✓ | ✗ | ✗ | -| {% ifversion ghec %} | -| Manage viewing of organization dependency insights (see [AUTOTITLE](/organizations/managing-organization-settings/changing-the-visibility-of-your-organizations-dependency-insights)) | ✓ | ✗ | ✗ | ✗ | ✗ | -| {% endif %} | -| Set a team profile picture in **all teams** (see [AUTOTITLE](/organizations/organizing-members-into-teams/setting-your-teams-profile-picture)) | ✓ | ✗ | ✗ | ✗ | ✗ | -| Sponsor accounts and manage the organization's sponsorships (see [AUTOTITLE](/sponsors/sponsoring-open-source-contributors)) | ✓ | ✗ | ✗ | ✓ | ✓ | -| Manage email updates from sponsored accounts (see [AUTOTITLE](/organizations/managing-organization-settings/managing-updates-from-accounts-your-organization-sponsors)) | ✓ | ✗ | ✗ | ✗ | ✗ | -| Attribute your sponsorships to another organization (see [AUTOTITLE](/sponsors/sponsoring-open-source-contributors/attributing-sponsorships-to-your-organization) for details ) | ✓ | ✗ | ✗ | ✗ | ✗ | -| Manage the publication of {% data variables.product.prodname_pages %} sites from repositories in the organization (see [AUTOTITLE](/organizations/managing-organization-settings/managing-the-publication-of-github-pages-sites-for-your-organization)) | ✓ | ✗ | ✗ | ✗ | ✗ | -| Manage security and analysis settings (see [AUTOTITLE](/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/managing-security-and-analysis-settings-for-your-organization)) | ✓ | ✗ | ✗ | ✗ | ✓ | -| View security overview for the organization (see [AUTOTITLE](/code-security/security-overview/about-security-overview)) | ✓ | ✗ | ✗ | ✗ | ✓ | -| {% ifversion ghec %} | -| Enable and enforce [SAML single sign-on](/organizations/managing-saml-single-sign-on-for-your-organization/about-identity-and-access-management-with-saml-single-sign-on) | ✓ | ✗ | ✗ | ✗ | ✗ | -| [Manage a user's SAML access to your organization](/organizations/granting-access-to-your-organization-with-saml-single-sign-on/viewing-and-managing-a-members-saml-access-to-your-organization) | ✓ | ✗ | ✗ | ✗ | ✗ | -| Manage an organization's SSH certificate authorities (see [AUTOTITLE](/organizations/managing-git-access-to-your-organizations-repositories/managing-your-organizations-ssh-certificate-authorities)) | ✓ | ✗ | ✗ | ✗ | ✗ | -| {% endif %} | -| Transfer repositories | ✓ | ✗ | ✗ | ✗ | ✗ | -| Purchase, install, manage billing for, and cancel {% data variables.product.prodname_marketplace %} apps | ✓ | ✗ | ✗ | ✗ | ✗ | -| List apps in {% data variables.product.prodname_marketplace %} | ✓ | ✗ | ✗ | ✗ | ✗ | -| Receive [{% data variables.product.prodname_dependabot_alerts %} about insecure dependencies](/code-security/dependabot/dependabot-alerts/about-dependabot-alerts) for all of an organization's repositories | ✓ | ✗ | ✗ | ✗ | ✓ | -| Manage {% data variables.product.prodname_dependabot_security_updates %} (see [AUTOTITLE](/code-security/dependabot/dependabot-security-updates/about-dependabot-security-updates)) | ✓ | ✗ | ✗ | ✗ | ✓ | -| [Manage the forking policy](/organizations/managing-organization-settings/managing-the-forking-policy-for-your-organization) | ✓ | ✗ | ✗ | ✗ | ✗ | -| [Limit activity in public repositories in an organization](/communities/moderating-comments-and-conversations/limiting-interactions-in-your-organization) | ✓ | ✗ | ✗ | ✗ | ✗ | -| Pull (read) _all repositories_ in the organization | ✓ | ✗ | ✗ | ✗ | ✓ | -| Push (write) and clone (copy) _all repositories_ in the organization | ✓ | ✗ | ✗ | ✗ | ✗ | -| Convert organization members to {% ifversion repository-collaborators %}[outside collaborators or repository collaborators](#outside-collaborators-or-repository-collaborators){% else %}[outside collaborators](#outside-collaborators){% endif %} | ✓ | ✗ | ✗ | ✗ | ✗ | -| [View people with access to an organization repository](/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/viewing-people-with-access-to-your-repository) | ✓ | ✗ | ✗ | ✗ | ✗ | -| {% ifversion ghec %} | -| [Export a list of people with access to an organization repository](/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/viewing-people-with-access-to-your-repository#exporting-a-list-of-people-with-access-to-your-repository) | ✓ | ✗ | ✗ | ✗ | ✗ | -| {% endif %} | -| Manage the default branch name (see [AUTOTITLE](/organizations/managing-organization-settings/managing-the-default-branch-name-for-repositories-in-your-organization)) | ✓ | ✗ | ✗ | ✗ | ✗ | -| Manage default labels (see [AUTOTITLE](/organizations/managing-organization-settings/managing-default-labels-for-repositories-in-your-organization)) | ✓ | ✗ | ✗ | ✗ | ✗ | -| {% ifversion ghec %} | -| Enable team synchronization (see [AUTOTITLE](/organizations/managing-saml-single-sign-on-for-your-organization/managing-team-synchronization-for-your-organization)) | ✓ | ✗ | ✗ | ✗ | ✗ | -| {% endif %} | -| Manage pull request reviews in the organization (see [AUTOTITLE](/organizations/managing-organization-settings/managing-pull-request-reviews-in-your-organization)) | ✓ | ✗ | ✗ | ✗ | ✗ | -| {% ifversion repo-rules-enterprise %} | -| Manage organization-level rulesets (see [AUTOTITLE](/organizations/managing-organization-settings/managing-rulesets-for-repositories-in-your-organization)) | ✓ | ✗ | ✗ | ✗ | ✗ | -| {% endif %} | -| {% ifversion push-protection-bypass-fine-grained-permissions %} | -| Review and manage {% data variables.product.prodname_secret_scanning %} bypass requests (see [AUTOTITLE](/code-security/secret-scanning/using-advanced-secret-scanning-and-push-protection-features/delegated-bypass-for-push-protection)) | ✓ | ✗ | ✗ | ✗ | ✓ | -| {% endif %} | -| {% ifversion security-delegated-alert-dismissal %} | -| Review and manage {% data variables.product.prodname_secret_scanning %} dismissal requests (see [AUTOTITLE](/code-security/secret-scanning/using-advanced-secret-scanning-and-push-protection-features/enabling-delegated-alert-dismissal-for-secret-scanning)) | ✓ | ✗ | ✗ | ✗ | ✓ | -| {% endif %} | -| {% ifversion security-delegated-alert-dismissal %} | -| Review and manage {% data variables.product.prodname_code_scanning %} dismissal requests (see [AUTOTITLE](/code-security/code-scanning/managing-your-code-scanning-configuration/enabling-delegated-alert-dismissal-for-code-scanning)) | ✓ | ✗ | ✗ | ✗ | ✓ | -| {% endif %} | -| {% ifversion dependabot-delegated-alert-dismissal %} | -| Review {% data variables.product.prodname_dependabot %} alert dismissal requests (see [AUTOTITLE](/code-security/dependabot/dependabot-alerts/enable-delegated-alert-dismissal)) | ✓ | ✗ | ✗ | ✗ | ✓ | -| Bypass {% data variables.product.prodname_dependabot %} alert dismissal requests (see [AUTOTITLE](/code-security/dependabot/dependabot-alerts/enable-delegated-alert-dismissal)) | ✓ | ✗ | ✗ | ✗ | ✓ | -| {% endif %} | - -{% endrowheaders %} - -{% elsif ghes %} - - -{% rowheaders %} - -| Organization action | Owners | Members | Security managers | -|:--------------------|:------:|:-------:|:-------:| -| Invite people to join the organization | ✓ | ✗ |✗ | -| Edit and cancel invitations to join the organization | ✓ | ✗ | ✗ | -| Remove members from the organization | ✓ | ✗ | ✗ | -| Reinstate former members to the organization | ✓ | ✗ | ✗ | -| Add and remove people from **all teams** | ✓ | ✗ | ✗ | -| Promote organization members to _team maintainer_ | ✓ | ✗ | ✗ | -| Configure code review assignments (see [AUTOTITLE](/organizations/organizing-members-into-teams/managing-code-review-settings-for-your-team)) | ✓ | ✗ | ✗ | -| Add collaborators to **all repositories** | ✓ | ✗ | ✗ | -| Access the organization audit log | ✓ | ✗ | ✗ | -| Edit the organization's profile page (see [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-github-profile/customizing-your-profile/about-your-organizations-profile)) | ✓ | ✗ | ✗ | -| Verify the organization's domains (see [AUTOTITLE](/organizations/managing-organization-settings/verifying-or-approving-a-domain-for-your-organization)) | ✓ | ✗ | ✗ | -| Restrict email notifications to verified or approved domains (see [AUTOTITLE](/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/restricting-email-notifications-for-your-organization)) | ✓ | ✗ | ✗ | -| Delete **all teams** | ✓ | ✗ | ✗ | -| Delete the organization account, including all repositories | ✓ | ✗ | ✗ | -| Create teams (see [AUTOTITLE](/organizations/managing-organization-settings/setting-team-creation-permissions-in-your-organization)) | ✓ | ✓ | ✓ | -| See all organization members and teams | ✓ | ✓ | ✓ | -| @mention any visible team | ✓ | ✓ | ✓ | -| Can be made a _team maintainer_ | ✓ | ✓ | ✓ | -| Transfer repositories | ✓ | ✗ | ✗ | -| Manage security and analysis settings (see [AUTOTITLE](/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/managing-security-and-analysis-settings-for-your-organization)) | ✓ | ✗ | ✓ | -| View the security overview for the organization (see [AUTOTITLE](/code-security/security-overview/about-the-security-overview)) | ✓ | ✗ | ✓ | -| {% ifversion security-delegated-alert-dismissal %} | -| Review and manage {% data variables.product.prodname_secret_scanning %} dismissal requests | ✓ | ✗ | ✓ | -| {% endif %} | -| {% ifversion security-delegated-alert-dismissal %} | -| Review and manage {% data variables.product.prodname_code_scanning %} dismissal requests | ✓ | ✗ | ✓ | -| {% endif %} | -| {% ifversion dependabot-delegated-alert-dismissal %} | -| Review {% data variables.product.prodname_dependabot %} alert dismissal requests | ✓ | ✗ | ✓ | -| Bypass {% data variables.product.prodname_dependabot %} alert dismissal requests | ✓ | ✗ | ✓ | -| {% endif %} | -| Manage {% data variables.product.prodname_dependabot_security_updates %} (see [AUTOTITLE](/code-security/dependabot/dependabot-security-updates/about-dependabot-security-updates)) | ✓ | ✗ | ✓ | -| Manage an organization's SSH certificate authorities (see [AUTOTITLE](/organizations/managing-git-access-to-your-organizations-repositories/managing-your-organizations-ssh-certificate-authorities)) | ✓ | ✗ | ✗ | -| {% ifversion projects-v1 %} | -| Create {% data variables.projects.projects_v1_boards %} (see [AUTOTITLE](/organizations/managing-access-to-your-organizations-project-boards/project-board-permissions-for-an-organization)) | ✓ | ✓ | ✓ | -| {% endif %} | -| Hide comments on commits, pull requests, and issues (see [AUTOTITLE](/communities/moderating-comments-and-conversations/managing-disruptive-comments#hiding-a-comment)) | ✓ | ✓ | ✓ | -| Set a team profile picture in **all teams** (see [AUTOTITLE](/organizations/organizing-members-into-teams/setting-your-teams-profile-picture)) | ✓ | ✗ | ✗ | -| Manage the publication of {% data variables.product.prodname_pages %} sites from repositories in the organization (see [AUTOTITLE](/organizations/managing-organization-settings/managing-the-publication-of-github-pages-sites-for-your-organization)) | ✓ | ✗ | ✗ | -| [Move teams in an organization's hierarchy](/organizations/organizing-members-into-teams/moving-a-team-in-your-organizations-hierarchy) | ✓ | ✗ | ✗ | -| Pull (read) _all repositories_ in the organization | ✓ | ✗ | ✓ | -| Push (write) and clone (copy) _all repositories_ in the organization | ✓ |✗ | ✗ | -| Convert organization members to {% ifversion repository-collaborators %}[outside collaborators or repository collaborators](#outside-collaborators-or-repository-collaborators){% else %}[outside collaborators](#outside-collaborators){% endif %} | ✓ | ✗ | ✗ | -| [View people with access to an organization repository](/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/viewing-people-with-access-to-your-repository) | ✓ | ✗ | ✗ | -| [Export a list of people with access to an organization repository](/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/viewing-people-with-access-to-your-repository#exporting-a-list-of-people-with-access-to-your-repository) | ✓ | ✗ | ✗ | -| Manage default labels (see [AUTOTITLE](/organizations/managing-organization-settings/managing-default-labels-for-repositories-in-your-organization)) | ✓ | ✗ | ✗ | -| {% ifversion pull-request-approval-limit %} | -| Manage pull request reviews in the organization (see [AUTOTITLE](/organizations/managing-organization-settings/managing-pull-request-reviews-in-your-organization)) | ✓ | ✗ | ✗ | -| {% endif %} | - -{% endrowheaders %} - -{% endif %} - -## Further reading +## Next steps -* [AUTOTITLE](/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/repository-roles-for-an-organization){% ifversion projects-v1 %} -* [AUTOTITLE](/organizations/managing-access-to-your-organizations-project-boards/project-board-permissions-for-an-organization){% endif %} +* [AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/managing-custom-organization-roles) \ No newline at end of file diff --git a/content/organizations/managing-peoples-access-to-your-organization-with-roles/using-organization-roles.md b/content/organizations/managing-peoples-access-to-your-organization-with-roles/using-organization-roles.md index 00de67fd896c..6127bf0ac5f5 100644 --- a/content/organizations/managing-peoples-access-to-your-organization-with-roles/using-organization-roles.md +++ b/content/organizations/managing-peoples-access-to-your-organization-with-roles/using-organization-roles.md @@ -22,10 +22,6 @@ In addition to pre-defined roles, you can also create up to 20 custom roles that {% ifversion org-pre-defined-roles %} -## About pre-defined organization roles - -{% data reusables.organizations.pre-defined-organization-roles %} - ## Viewing organization role permissions {% data reusables.profile.access_org %} diff --git a/data/reusables/organizations/pre-defined-organization-roles.md b/data/reusables/organizations/pre-defined-organization-roles.md deleted file mode 100644 index aa773cded3b3..000000000000 --- a/data/reusables/organizations/pre-defined-organization-roles.md +++ /dev/null @@ -1,16 +0,0 @@ -Pre-defined organization roles are roles that are available by default in every organization. You don't need to create them yourself. They can include both organization permissions that let the recipient manage the organization, as well as repository permissions that apply to all of the repositories in the organization. The following pre-defined roles are built into every organization based on common patterns of permissions organizations usually need. - -The current set of pre-defined roles are: - -* **All-repository read:** Grants read access to all repositories in the organization. -* **All-repository write:** Grants write access to all repositories in the organization. -* **All-repository triage:** Grants triage access to all repositories in the organization. -* **All-repository maintain:** Grants maintenance access to all repositories in the organization. -* **All-repository admin:** Grants admin access to all repositories in the organization. -{%- ifversion fpt or ghec or ghes > 3.15 %} -* **CI/CD admin:** Grants admin access to manage Actions policies, runners, runner groups, hosted compute network configurations, secrets, variables, and usage metrics for an organization. -* **Security manager**: Grants the ability to manage security policies, security alerts, and security configurations for an organization and all its repositories. -{%- endif %} -{%- ifversion org-app-manager-teams %} -* **App Manager:** Grants the ability to create, edit, and delete all GitHub Apps in an organization. -{%- endif %} From 488b096edf28238dea40381a87c19bb9e074fad8 Mon Sep 17 00:00:00 2001 From: John Clement <70238417+jclement136@users.noreply.github.com> Date: Fri, 6 Mar 2026 12:14:19 -0500 Subject: [PATCH 4/4] [EDI] Optimizing Java packages for Dependabot updates (#59809) --- .../manage-your-dependency-security/index.md | 1 - .../reference/supply-chain-security/index.md | 2 ++ .../java-package-metadata-dependabot.md} | 19 +++++++++---------- 3 files changed, 11 insertions(+), 11 deletions(-) rename content/code-security/{how-tos/secure-your-supply-chain/manage-your-dependency-security/optimizing-java-packages-dependabot.md => reference/supply-chain-security/java-package-metadata-dependabot.md} (53%) diff --git a/content/code-security/how-tos/secure-your-supply-chain/manage-your-dependency-security/index.md b/content/code-security/how-tos/secure-your-supply-chain/manage-your-dependency-security/index.md index 9bc769b84863..abe80408e5f5 100644 --- a/content/code-security/how-tos/secure-your-supply-chain/manage-your-dependency-security/index.md +++ b/content/code-security/how-tos/secure-your-supply-chain/manage-your-dependency-security/index.md @@ -13,7 +13,6 @@ children: - /customizing-dependabot-security-prs - /controlling-dependencies-updated - /configuring-the-dependency-review-action - - /optimizing-java-packages-dependabot - /configuring-notifications-for-dependabot-alerts - /configuring-access-to-private-registries-for-dependabot - /removing-dependabot-access-to-public-registries diff --git a/content/code-security/reference/supply-chain-security/index.md b/content/code-security/reference/supply-chain-security/index.md index 5d2cc455a9b8..6c57e7b0e569 100644 --- a/content/code-security/reference/supply-chain-security/index.md +++ b/content/code-security/reference/supply-chain-security/index.md @@ -27,6 +27,8 @@ children: - /dependabot-on-actions - /criteria-for-preset-rules - /troubleshoot-dependabot + - /java-package-metadata-dependabot + redirect_from: - /code-security/dependabot/ecosystems-supported-by-dependabot --- diff --git a/content/code-security/how-tos/secure-your-supply-chain/manage-your-dependency-security/optimizing-java-packages-dependabot.md b/content/code-security/reference/supply-chain-security/java-package-metadata-dependabot.md similarity index 53% rename from content/code-security/how-tos/secure-your-supply-chain/manage-your-dependency-security/optimizing-java-packages-dependabot.md rename to content/code-security/reference/supply-chain-security/java-package-metadata-dependabot.md index 4553e25f94fd..d6c5b258c69d 100644 --- a/content/code-security/how-tos/secure-your-supply-chain/manage-your-dependency-security/optimizing-java-packages-dependabot.md +++ b/content/code-security/reference/supply-chain-security/java-package-metadata-dependabot.md @@ -1,7 +1,7 @@ --- -title: Optimizing Java packages for Dependabot updates -intro: By including metadata in your `pom.xml` file, you can enhance the information available to users in {% data variables.product.prodname_dependabot%} pull requests to update your Java packages. -shortTitle: Optimize Java packages +title: Java package metadata for Dependabot updates +intro: Include metadata in your `pom.xml` file to provide helpful links and context in {% data variables.product.prodname_dependabot %} pull requests for Java package updates. +shortTitle: Java package metadata allowTitleToDifferFromFilename: true versions: fpt: '*' @@ -13,18 +13,19 @@ topics: - Repositories redirect_from: - /code-security/dependabot/ecosystems-supported-by-dependabot/optimizing-java-packages-dependabot + - /code-security/how-tos/secure-your-supply-chain/manage-your-dependency-security/optimizing-java-packages-dependabot contentType: how-tos --- -{% data variables.product.prodname_dependabot %} uses the information defined in `pom.xml` files to create pull requests to update Java dependencies for the Gradle and Maven ecosystems. When you include the project metadata that {% data variables.product.prodname_dependabot %} expects, pull requests contain links to the release notes for the suggested package update and a link where users can report any issues. This information means that users can update their packages with confidence after reviewing all the release information. +{% data variables.product.prodname_dependabot %} uses the `url`, `scm`, and `issueManagement` fields in `pom.xml` files to create pull requests for Java dependency updates. When you include this metadata, pull requests will contain links to release notes and issue trackers, helping users update packages with confidence. -## Including the metadata {% data variables.product.prodname_dependabot %} needs in pom.xml files +## Metadata that {% data variables.product.prodname_dependabot %} needs in pom.xml files {% data variables.product.prodname_dependabot %} uses the URLs for the project, the source code management system, and the issue management system to build the summary for update pull requests. -* `url` the home page for the project, see [More Project Information](https://maven.apache.org/pom.html#More_Project_Information) in the POM reference -* `scm` the URL of the source code management system used by the project, see [SCM](https://maven.apache.org/pom.html#scm) in the POM Reference -* `issueManagement` the URL of the issue management system used by the project, see [Issue Management](https://maven.apache.org/pom.html#issue-management) in the POM Reference +* `url`: The home page for the project. See [More Project Information](https://maven.apache.org/pom.html#More_Project_Information) in the POM reference +* `scm`: The URL of the source code management system used by the project. See [SCM](https://maven.apache.org/pom.html#scm) in the POM Reference +* `issueManagement`: The URL of the issue management system used by the project. See [Issue Management](https://maven.apache.org/pom.html#issue-management) in the POM Referencex ### Example for a project hosted on {% data variables.product.github %} @@ -40,8 +41,6 @@ contentType: how-tos ``` -Replace `OWNER` and `REPOSITORY` with the detailed for your project. - ## Impact of omitting project metadata from pom.xml files If you forget to include the URLs that {% data variables.product.prodname_dependabot %} checks for, then pull requests to update Java packages are still created. However, the information available to users in the pull request summary will be limited.