diff --git a/assets/images/help/security/security-campaigns-tracking-overview.png b/assets/images/help/security/security-campaigns-tracking-overview.png deleted file mode 100644 index 16aa63b6564b..000000000000 Binary files a/assets/images/help/security/security-campaigns-tracking-overview.png and /dev/null differ diff --git a/assets/images/help/security/virtual-registry-decommissioned.png b/assets/images/help/security/virtual-registry-decommissioned.png new file mode 100644 index 000000000000..a4d8422b7d4f Binary files /dev/null and b/assets/images/help/security/virtual-registry-decommissioned.png differ diff --git a/assets/images/help/security/virtual-registry-deleted.png b/assets/images/help/security/virtual-registry-deleted.png new file mode 100644 index 000000000000..f8e9182acc68 Binary files /dev/null and b/assets/images/help/security/virtual-registry-deleted.png differ diff --git a/assets/images/help/security/virtual-registry-deployment-record.png b/assets/images/help/security/virtual-registry-deployment-record.png new file mode 100644 index 000000000000..89baa0b6bc83 Binary files /dev/null and b/assets/images/help/security/virtual-registry-deployment-record.png differ diff --git a/assets/images/help/security/virtual-registry-storage-record.png b/assets/images/help/security/virtual-registry-storage-record.png new file mode 100644 index 000000000000..2f2411c051e0 Binary files /dev/null and b/assets/images/help/security/virtual-registry-storage-record.png differ diff --git a/content/actions/how-tos/deploy/configure-and-manage-deployments/control-deployments.md b/content/actions/how-tos/deploy/configure-and-manage-deployments/control-deployments.md index 911bf54a87c9..3c2d25aa01c2 100644 --- a/content/actions/how-tos/deploy/configure-and-manage-deployments/control-deployments.md +++ b/content/actions/how-tos/deploy/configure-and-manage-deployments/control-deployments.md @@ -128,6 +128,12 @@ For guidance on writing deployment-specific steps, see [Finding deployment examp When a {% data variables.product.prodname_actions %} workflow deploys to an environment, the environment is displayed on the main page of the repository. For more information about viewing deployments to environments, see [AUTOTITLE](/actions/deployment/managing-your-deployments/viewing-deployment-history). +{% ifversion virtual-registry %} + +Your organization can collect deployment records for all your builds in a single place by uploading data to the {% data variables.product.virtual_registry %}. See [AUTOTITLE](/code-security/concepts/supply-chain-security/linked-artifacts). + +{% endif %} + ## Monitoring workflow runs Every workflow run generates a real-time graph that illustrates the run progress. You can use this graph to monitor and debug deployments. For more information see, [AUTOTITLE](/actions/monitoring-and-troubleshooting-workflows/using-the-visualization-graph). diff --git a/content/actions/how-tos/secure-your-work/use-artifact-attestations/use-artifact-attestations.md b/content/actions/how-tos/secure-your-work/use-artifact-attestations/use-artifact-attestations.md index 50013ab488b4..03613a07a560 100644 --- a/content/actions/how-tos/secure-your-work/use-artifact-attestations/use-artifact-attestations.md +++ b/content/actions/how-tos/secure-your-work/use-artifact-attestations/use-artifact-attestations.md @@ -141,6 +141,14 @@ When you run your updated workflows, they will build your artifacts and generate The value of the `sbom-path` parameter should be set to the path to the JSON-formatted SBOM file you want to attest. +## Uploading artifacts to the {% data variables.product.virtual_registry %} + +We recommend uploading attested assets to your organization's {% data variables.product.virtual_registry %}. This page displays artifacts' build history, deployment records, and storage details. You can use this data to prioritize security alerts or quickly connect vulnerable artifacts to their owning team, source code, and build run. For more information, see [AUTOTITLE](/code-security/concepts/supply-chain-security/linked-artifacts). + +{% data reusables.actions.attestation-virtual-registry %} + +For an example workflow, see [AUTOTITLE](/code-security/how-tos/secure-your-supply-chain/establish-provenance-and-integrity/upload-linked-artifacts#generating-an-attestation). + ## Verifying artifact attestations with the {% data variables.product.prodname_cli %} You can validate artifact attestations for binaries and container images and validate SBOM attestations using the {% data variables.product.prodname_cli %}. For more information, see the [`attestation`](https://cli.github.com/manual/gh_attestation) section of the {% data variables.product.prodname_cli %} manual. diff --git a/content/code-security/concepts/supply-chain-security/about-supply-chain-security.md b/content/code-security/concepts/supply-chain-security/about-supply-chain-security.md index fdf9ad43a1e9..c4b44fa491f5 100644 --- a/content/code-security/concepts/supply-chain-security/about-supply-chain-security.md +++ b/content/code-security/concepts/supply-chain-security/about-supply-chain-security.md @@ -39,10 +39,14 @@ The supply chain features on {% data variables.product.github %} are: * **{% data variables.product.prodname_dependabot_updates %}** * **{% data variables.product.prodname_dependabot_security_updates %}** * **{% data variables.product.prodname_dependabot_version_updates %}** +{%- ifversion fpt or ghec %} +* **Immutable releases** +* **Artifact attestations** +{%- endif %} The dependency graph is central to supply chain security. The dependency graph identifies all upstream dependencies and public downstream dependents of a repository or package. Your repository’s dependency graph tracks and displays its dependencies and some of their properties, like vulnerability information. -Other supply chain features on {% data variables.product.prodname_dotcom %} rely on the information provided by the dependency graph. +The following supply chain features on {% data variables.product.prodname_dotcom %} rely on the information provided by the dependency graph. * Dependency review uses the dependency graph to identify dependency changes and help you understand the security impact of these changes when you review pull requests. * {% data variables.product.prodname_dependabot %} cross-references dependency data provided by the dependency graph with the list of advisories published in the {% data variables.product.prodname_advisory_database %}, scans your dependencies and generates {% data variables.product.prodname_dependabot_alerts %} when a potential vulnerability is detected. @@ -136,6 +140,20 @@ There are two types of {% data variables.product.prodname_dependabot_updates %}: For more information about {% data variables.product.prodname_dependabot_updates %}, see [AUTOTITLE](/code-security/dependabot/dependabot-security-updates/about-dependabot-security-updates) and [AUTOTITLE](/code-security/dependabot/dependabot-version-updates/about-dependabot-version-updates). +### What are immutable releases? + +Repositories can enable immutable releases to prevent the assets and associated Git tag of a release from being changed after publication. This reduces the risk of supply chain attacks by preventing attackers from injecting vulnerabilities into releases you consume. It also means projects that rely on specific releases are less likely to break. + +Creating an immutable release automatically generates an attestation for the release. You can use this attestation to make sure the release and its artifacts match the published information. + +### What are artifact attestations? + +Software providers can generate attestations for software built with {% data variables.product.prodname_actions %}. Attestations are cryptographically signed claims that establish the build's provenance (the source code and workflow run used to build it) or associated software bill of materials (SBOM). + +You can increase supply chain security by verifying attestations for your dependencies. Although attestations do not guarantee security, they give you information about where and how software was built, so you can be more confident that your dependencies haven't been tampered with. You can gate deployments using a tool like the Kubernetes admissions controller to prevent unattested builds from being deployed. + +When you use {% data variables.product.prodname_actions %} to generate attestations for your organization's own builds, the built artifacts are automatically uploaded to the {% data variables.product.virtual_registry %}. This platform allows you to view the storage and deployment records of all linked artifacts, so you can find the source code and workflow run used to build an artifact or filter security alerts based on deployment context. + ## Feature availability {% ifversion fpt or ghec %} @@ -145,17 +163,19 @@ Public repositories: * **Dependency review:** Enabled by default and cannot be disabled. * **{% data variables.product.prodname_dependabot_alerts %}:** Not enabled by default. {% data variables.product.prodname_dotcom %} detects insecure dependencies and displays information in the dependency graph, but does not generate {% data variables.product.prodname_dependabot_alerts %} by default. Repository owners or people with admin access can enable {% data variables.product.prodname_dependabot_alerts %}. You can also enable or disable Dependabot alerts for all repositories owned by your user account or organization. For more information, see [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-personal-account-settings/managing-security-and-analysis-settings-for-your-personal-account) or [AUTOTITLE](/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/managing-security-and-analysis-settings-for-your-organization). +* **Artifact attestations:** Available in all public repositories, but you must explicitly generate attestations in your build workflows. See [AUTOTITLE](/actions/how-tos/secure-your-work/use-artifact-attestations/use-artifact-attestations). Private repositories: * **Dependency graph:** Not enabled by default. The feature can be enabled by repository administrators. For more information, see [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/exploring-the-dependencies-of-a-repository#enabling-and-disabling-the-dependency-graph). * **Dependency review:** Available in private repositories owned by organizations that use {% data variables.product.prodname_team %} or {% data variables.product.prodname_ghe_cloud %} and have a license for {% data variables.product.prodname_GHAS_or_code_security %}. For more information, see [AUTOTITLE](/get-started/learning-about-github/about-github-advanced-security) and [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/exploring-the-dependencies-of-a-repository#enabling-and-disabling-the-dependency-graph). - * **{% data variables.product.prodname_dependabot_alerts %}:** Not enabled by default. Owners of private repositories, or people with admin access, can enable {% data variables.product.prodname_dependabot_alerts %} by enabling the dependency graph and {% data variables.product.prodname_dependabot_alerts %} for their repositories. You can also enable or disable Dependabot alerts for all repositories owned by your user account or organization. For more information, see [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-personal-account-settings/managing-security-and-analysis-settings-for-your-personal-account) or [AUTOTITLE](/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/managing-security-and-analysis-settings-for-your-organization). +* **Artifact attestations:** Only available in private repositories on {% data variables.product.prodname_ghe_cloud %}. Any repository type: * **{% data variables.product.prodname_dependabot_security_updates %}:** Not enabled by default. You can enable {% data variables.product.prodname_dependabot_security_updates %} for any repository that uses {% data variables.product.prodname_dependabot_alerts %} and the dependency graph. For information about enabling security updates, see [AUTOTITLE](/code-security/dependabot/dependabot-security-updates/configuring-dependabot-security-updates). * **{% data variables.product.prodname_dependabot_version_updates %}:** Not enabled by default. People with write permissions to a repository can enable {% data variables.product.prodname_dependabot_version_updates %}. For information about enabling version updates, see [AUTOTITLE](/code-security/dependabot/dependabot-version-updates/configuring-dependabot-version-updates). +* **Immutable releases*:** Not enabled by default. You can enable release immutability for a repository or organization. See [AUTOTITLE](/code-security/how-tos/secure-your-supply-chain/establish-provenance-and-integrity/preventing-changes-to-your-releases). {% endif %} {% ifversion ghes %} diff --git a/content/code-security/concepts/supply-chain-security/index.md b/content/code-security/concepts/supply-chain-security/index.md index a36c4d78ab51..b194f07ed4c1 100644 --- a/content/code-security/concepts/supply-chain-security/index.md +++ b/content/code-security/concepts/supply-chain-security/index.md @@ -19,4 +19,5 @@ children: - about-dependabot-auto-triage-rules - about-dependabot-on-github-actions-runners - immutable-releases + - linked-artifacts --- diff --git a/content/code-security/concepts/supply-chain-security/linked-artifacts.md b/content/code-security/concepts/supply-chain-security/linked-artifacts.md new file mode 100644 index 000000000000..6d1a65dcdc90 --- /dev/null +++ b/content/code-security/concepts/supply-chain-security/linked-artifacts.md @@ -0,0 +1,71 @@ +--- +title: About linked artifacts +intro: "The {% data variables.product.virtual_registry %} helps you audit and prioritize your organization's builds on {% data variables.product.github %}, regardless of where the artifacts are stored." +versions: + feature: virtual-registry +shortTitle: 'Linked artifacts' +topics: + - Vulnerabilities + - Dependencies +contentType: concepts +--- + +The {% data variables.product.virtual_registry %} provides a unified view of software artifacts that your organization builds with {% data variables.product.prodname_actions %}, such as container images, packages, or builds of your production code. + +The page shows you how an artifact was built, where it is stored or running, and which compliance and security metadata is associated with the artifact. + +Teams in your organization can use the {% data variables.product.virtual_registry %} to: + +* Prioritize alerts from {% data variables.product.prodname_GHAS %} features based on whether the detected vulnerabilities are running in production or exposed to the internet +* Quickly connect artifacts to build details, storage locations, and owning teams +* Meet compliance by exporting auditable proof of your artifacts' provenance and integrity + +## Which artifacts appear on the {% data variables.product.virtual_registry %}? + +The {% data variables.product.virtual_registry %} is unique to each organization. It contains metadata for artifacts that have been built with {% data variables.product.prodname_actions %} in your organization's repositories. It does **not** display artifacts your organization consumes from elsewhere, such as open source dependencies. + +Artifact records are uploaded by your organization using either a public API or an integration with an external registry. The {% data variables.product.virtual_registry %} does not store the artifact files themselves. It just provides an authoritative source for the metadata associated with each artifact. + +Because an artifact does not need to be stored on {% data variables.product.github %} to appear in the {% data variables.product.virtual_registry %}, you can use the {% data variables.product.virtual_registry %} alongside your preferred package registry, such as JFrog Artifactory or {% data variables.product.prodname_registry %}. + +## Which metadata is included? + +The {% data variables.product.virtual_registry %} combines data from two different types of record: storage records and deployment records. These records are uploaded using different API endpoints or integrations. + +### Storage records + +Storage records include the repository containing the artifact's source code, the registry where the artifact is stored, and any attestations proving the artifact's integrity and provenance. You can use this data to quickly find an artifact's owning team and build details. + +![Screenshot of an artifact page. Highlighted fields: storage registry, artifact repository, source repository.](/assets/images/help/security/virtual-registry-storage-record.png) + +For more information about attestations and SLSA levels, see [AUTOTITLE](/actions/concepts/security/artifact-attestations). + +### Deployment records + +Deployment records include the environment where the artifact is deployed and any runtime risks (such as "sensitive data" or "internet exposed") associated with the artifact. You can use this data to filter security alerts based on the level of threat posed to your organization and consumers. + +![Screenshot of an artifact page. Highlighted fields: the "Deployments" list, including tags for "Prod", "sensitive data", and "pacific-east".](/assets/images/help/security/virtual-registry-deployment-record.png) + +>[!NOTE] Deployment records do **not** include deployment activity from a repository's deployments dashboard, which comes from a different source. See [AUTOTITLE](/repositories/viewing-activity-and-data-for-your-repository/viewing-deployment-activity-for-your-repository). + +## How does the {% data variables.product.virtual_registry %} fit into my processes? + +This example workflow shows how the {% data variables.product.virtual_registry %} integrates with other {% data variables.product.github %} features and external systems. + +1. A developer commits code to a {% data variables.product.github %} repository where the code for a software package is defined. +1. A {% data variables.product.prodname_actions %} workflow in the repository automatically: + + 1. Builds the package. + 1. Pushes the package to your chosen registry, such as {% data variables.product.prodname_registry %} or JFrog Artifactory. + 1. Creates a cryptographically signed provenance attestation, linking the package to the repository, commit, and workflow used to build the package. + 1. Deploys the package to a staging or production environment. Your deployment system may be gated to ensure that only attested artifacts can be deployed to production, for example using the Kubernetes Admissions Controller. + +1. Metadata for the package, such as its linked repository, attestations, and deployment history, is uploaded to the {% data variables.product.virtual_registry %}. +1. Using the data from the {% data variables.product.virtual_registry %}, a security lead triages code scanning and Dependabot alerts, and creates a campaign to address alerts that affect production environments or have a specific runtime risk. +1. When an audit is required, a member of the compliance team exports SBOMs, provenance details, and deployment records for all your organization's linked artifacts from a single source. + +## Next steps + +To add records to your organization's {% data variables.product.virtual_registry %}, see [AUTOTITLE](/code-security/how-tos/secure-your-supply-chain/establish-provenance-and-integrity/upload-linked-artifacts). + +To view the {% data variables.product.virtual_registry %} for your organization, see [AUTOTITLE](/code-security/how-tos/secure-your-supply-chain/establish-provenance-and-integrity/view-linked-artifacts). diff --git a/content/code-security/how-tos/secure-your-supply-chain/establish-provenance-and-integrity/index.md b/content/code-security/how-tos/secure-your-supply-chain/establish-provenance-and-integrity/index.md index bcd45b5d263d..e9336ee5b70c 100644 --- a/content/code-security/how-tos/secure-your-supply-chain/establish-provenance-and-integrity/index.md +++ b/content/code-security/how-tos/secure-your-supply-chain/establish-provenance-and-integrity/index.md @@ -10,5 +10,8 @@ contentType: how-tos children: - /preventing-changes-to-your-releases - /exporting-a-software-bill-of-materials-for-your-repository + - /upload-linked-artifacts + - /view-linked-artifacts + - /remove-linked-artifacts --- diff --git a/content/code-security/how-tos/secure-your-supply-chain/establish-provenance-and-integrity/remove-linked-artifacts.md b/content/code-security/how-tos/secure-your-supply-chain/establish-provenance-and-integrity/remove-linked-artifacts.md new file mode 100644 index 000000000000..190a953f007e --- /dev/null +++ b/content/code-security/how-tos/secure-your-supply-chain/establish-provenance-and-integrity/remove-linked-artifacts.md @@ -0,0 +1,33 @@ +--- +title: Removing artifacts from the {% data variables.product.virtual_registry %} +intro: "Set the storage and deployment status of artifacts to reflect that they are no longer in use." +versions: + feature: virtual-registry +topics: + - Vulnerabilities + - Dependencies +contentType: concepts +product: 'Organization accounts on any plan' +permissions: 'Write access to the repository where an artifact is built' +shortTitle: Remove linked artifacts +--- + +It is **not possible** to delete an artifact from the {% data variables.product.virtual_registry %}. However, if an artifact has been removed from your organization's registry or is no longer deployed anywhere, you can update an artifact's storage or deployment record to reflect its status. + +## Updating a storage record + +When you delete an artifact from your external registry, you can use the [Create artifact metadata storage record](/rest/orgs/artifact-metadata#create-artifact-metadata-storage-record) API endpoint to set the status of an existing artifact to `deleted`. You can also mark an artifact as `eol`. + +This information is displayed as a tag next to the artifact repository name. + +![Screenshot of the artifact page. The "deleted" tag is highlighted in orange.](/assets/images/help/security/virtual-registry-deleted.png) + +If you have deleted an artifact from a registry, you should also remove any attestations associated with the artifact. See [AUTOTITLE](/actions/how-tos/secure-your-work/use-artifact-attestations/manage-attestations). + +## Updating a deployment record + +When an artifact stops being deployed in a given environment, you can use the [Create an artifact deployment record](/rest/orgs/artifact-metadata#create-an-artifact-deployment-record) API endpoint to set the deployment's status to `decommissioned`. + +This information is reflected in the icon next to the deployment record. + +![Screenshot of the artifact page. A cloud icon with a line through it is highlighted in orange.](/assets/images/help/security/virtual-registry-decommissioned.png) diff --git a/content/code-security/how-tos/secure-your-supply-chain/establish-provenance-and-integrity/upload-linked-artifacts.md b/content/code-security/how-tos/secure-your-supply-chain/establish-provenance-and-integrity/upload-linked-artifacts.md new file mode 100644 index 000000000000..dea89c9bbc37 --- /dev/null +++ b/content/code-security/how-tos/secure-your-supply-chain/establish-provenance-and-integrity/upload-linked-artifacts.md @@ -0,0 +1,167 @@ +--- +title: Uploading storage and deployment data to the {% data variables.product.virtual_registry %} +intro: "Associate packages and builds in your organization with storage and deployment data." +versions: + feature: virtual-registry +topics: + - Vulnerabilities + - Dependencies +contentType: concepts +product: 'Organization accounts on any plan' +permissions: 'Anyone with write access to an organization-owned repository' +shortTitle: Upload linked artifacts +--- + +The {% data variables.product.virtual_registry %} includes storage records and deployment records for artifacts that you build in your organization. Metadata for each artifact is provided by your organization using one of the following methods: + +* A workflow containing one of {% data variables.product.company_short %}'s actions for **artifact attestations** +* An integration with the **JFrog Artifactory** or **Microsoft Defender for Cloud** +* A custom script using the **artifact metadata REST API** + +The available methods depend on whether you are uploading a storage record or a deployment record. For more information about record types, see [AUTOTITLE](/code-security/concepts/supply-chain-security/linked-artifacts#which-metadata-is-included). + +## Uploading a storage record + +You can upload a storage record by creating an **artifact attestation** or enabling an integration with **JFrog Artifactory**. If you don't want to use these options, you must set up a custom integration with the **REST API**. + +### Attesting with {% data variables.product.prodname_actions %} + +You can upload a storage record for an artifact using {% data variables.product.github %}'s first-party actions for artifact attestations. You can do this in the same workflow you use to build the artifact. These actions create signed provenance and integrity guarantees for the software you build, as well as automatically uploading a storage record to the {% data variables.product.virtual_registry %}. + +{% data reusables.actions.attestation-virtual-registry %} + +For more information on using these actions, see [AUTOTITLE](/actions/how-tos/secure-your-work/use-artifact-attestations/use-artifact-attestations). + +If the artifact does not require attestation, or if you want to upload deployment records or additional storage metadata, see the following sections. + +### Using the JFrog integration + +This two-way integration automatically keeps your storage records on {% data variables.product.github %} up to date with the artifact on JFrog. For example, attestations you create on {% data variables.product.github %} are automatically uploaded to JFrog, and promoting an artifact to production on JFrog automatically adds the production context to the record on {% data variables.product.github %}. + +For setup instructions, see [Get Started with JFrog Artifactory and GitHub Integration](https://jfrog.com/help/r/jfrog-and-github-integration-guide/get-started-with-jfrog-artifactory-and-github-integration) in the JFrog documentation. + +### Using the REST API + +For artifacts that do not need to be attested and are not stored on JFrog, you can create a custom integration using the [Create artifact metadata storage record](/rest/orgs/artifact-metadata#create-artifact-metadata-storage-record) API endpoint. You should configure your system to call the endpoint whenever an artifact is published to your chosen package repository. + +>[!NOTE] If the artifact is not associated with a provenance attestation on {% data variables.product.github %}, the `github_repository` parameter is mandatory. + +## Uploading a deployment record + +If you store artifacts in **{% data variables.product.prodname_mdc_definition %}**, you can use an integration to automatically sync data to the {% data variables.product.virtual_registry %}. Otherwise, you must set up a custom integration with the **REST API**. + +### Using the Microsoft Defender for Cloud integration + +You can connect your {% data variables.product.prodname_mdc %} instance to your {% data variables.product.github %} organization. {% data variables.product.prodname_mdc %} will automatically send deployment and runtime data to {% data variables.product.github %}. + +For setup instructions, see [Quick Start: Connect your {% data variables.product.github %} Environment to {% data variables.product.prodname_microsoft_defender %}](https://learn.microsoft.com/en-us/azure/defender-for-cloud/quickstart-onboard-github) in the documentation for {% data variables.product.prodname_mdc %}. + +{% data reusables.security.production-context-mdc-preview %} + +### Using the REST API + +The [Create an artifact deployment record](/rest/orgs/artifact-metadata#create-an-artifact-deployment-record) API endpoint allows systems to send deployment data for a specific artifact to {% data variables.product.github %}, such as its name, digest, environments, cluster, and deployment. You should call this endpoint whenever an artifact is deployed to a new staging or production environment. + +>[!NOTE] If the artifact is not associated with a provenance attestation on {% data variables.product.github %}, the `github_repository` parameter is mandatory. + +## Verifying an upload + +To check that a record has been uploaded successfully, you can view the updated artifact in your organization settings. See [AUTOTITLE](/code-security/how-tos/secure-your-supply-chain/establish-provenance-and-integrity/view-linked-artifacts). + +## Removing unwanted records + +It is not possible to delete an artifact from the {% data variables.product.virtual_registry %}. However, you can update a storage record or deployment record to reflect an artifact's status. See [AUTOTITLE](/code-security/how-tos/secure-your-supply-chain/establish-provenance-and-integrity/remove-linked-artifacts). + +## {% data variables.product.prodname_actions %} examples + +You can upload data to the {% data variables.product.virtual_registry %} in the same workflow you use to build and publish an artifact. + +### Generating an attestation + +In the following example, we build and publish a Docker image, then use the `{% raw %}${{ steps.push.outputs.digest }}{% endraw %}` output in the next step to generate a provenance attestation. + +The `attest-build-provenance` action automatically uploads a storage record to the {% data variables.product.virtual_registry %} when `push-to-registry: true` is set and the workflow includes the `artifact-metadata: write` permission. + +``` yaml +{% raw %} +env: + IMAGE_NAME: my-container-image + ACR_ENDPOINT: my-registry.azurecr.io + +jobs: + generate-build: + name: Build and publish Docker image + runs-on: ubuntu-latest + permissions: + id-token: write + contents: read + attestations: write + packages: write + artifact-metadata: write + + steps: + - name: Build and push Docker image + id: push + uses: docker/build-push-action@263435318d21b8e681c14492fe198d362a7d2c83 + with: + context: . + push: true + tags: | + ${{ env.ACR_ENDPOINT }}/${{ env.IMAGE_NAME }}:latest + ${{ env.ACR_ENDPOINT }}/${{ env.IMAGE_NAME }}:${{ github.sha }} + + - name: Generate artifact attestation + uses: actions/attest-build-provenance@v3 + with: + subject-name: ${{ env.ACR_ENDPOINT }}/${{ env.IMAGE_NAME }} + subject-digest: ${{ steps.push.outputs.digest }} + push-to-registry: true +{% endraw %} +``` + +### Using the REST API + +Alternatively, if you are not generating an attestation, you can call the artifact metadata API directly. + +``` yaml +{% raw %} +env: + IMAGE_NAME: my-container-image + IMAGE_VERSION: 1.1.2 + ACR_ENDPOINT: my-registry.azurecr.io + +jobs: + generate-build: + name: Build and publish Docker image + runs-on: ubuntu-latest + permissions: + id-token: write + contents: read + packages: write + artifact-metadata: write + + steps: + - name: Build and push Docker image + id: push + uses: docker/build-push-action@263435318d21b8e681c14492fe198d362a7d2c83 + with: + context: . + push: true + tags: | + ${{ env.ACR_ENDPOINT }}/${{ env.IMAGE_NAME }}:latest + ${{ env.ACR_ENDPOINT }}/${{ env.IMAGE_NAME }}:${{ github.sha }} + + - name: Create artifact metadata storage record + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + run: | + jq -n --arg artifactName "${{ env.IMAGE_NAME }}" --arg artifactVersion "${{ env.IMAGE_VERSION }}" --arg artifactDigest "${{ steps.push.outputs.digest }}" '{"name": $artifactName, "digest": $artifactDigest, "version": $artifactVersion, "registry_url": "https://azurecr.io", "repository": "my-repository"}' > create-record.json + + gh api -X POST orgs/${{ github.repository_owner }}/artifacts/metadata/storage-record --input create-record.json + shell: bash +{% endraw %} +``` + +## Next steps + +Once you have uploaded data, teams in your organization can use the context from storage and deployment data to prioritize security alerts. See [AUTOTITLE](/code-security/tutorials/secure-your-organization/prioritize-alerts-in-production-code). diff --git a/content/code-security/how-tos/secure-your-supply-chain/establish-provenance-and-integrity/view-linked-artifacts.md b/content/code-security/how-tos/secure-your-supply-chain/establish-provenance-and-integrity/view-linked-artifacts.md new file mode 100644 index 000000000000..1ef7a7d933c2 --- /dev/null +++ b/content/code-security/how-tos/secure-your-supply-chain/establish-provenance-and-integrity/view-linked-artifacts.md @@ -0,0 +1,32 @@ +--- +title: Auditing your organization's builds on the {% data variables.product.virtual_registry %} +intro: "View or export metadata for build runs, storage details, and deployment context." +versions: + feature: virtual-registry +topics: + - Vulnerabilities + - Dependencies +contentType: concepts +product: 'Organization accounts on any plan' +permissions: 'Anyone with read access to an organization-owned repository' +shortTitle: View linked artifacts +--- + +You can use the {% data variables.product.virtual_registry %} to connect your organization's artifacts to their build details, deployment context, and security metadata. The {% data variables.product.virtual_registry %} collects metadata for artifacts built with {% data variables.product.prodname_actions %} in your organization's repositories, regardless of whether the artifacts are stored on {% data variables.product.github %}. For more information, see [AUTOTITLE](/code-security/concepts/supply-chain-security/linked-artifacts). + +## Viewing an artifact + +{% data reusables.package_registry.package-settings-from-org-level %} +1. In the left sidebar, click **Linked artifacts**. +1. Click the artifact you want to view. +1. On the artifact's page, you can: + + * View the artifact's deployment history and registry storage details + * Click through to the repository where the artifact's source code is defined + * If available, click on the artifact's provenance attestation to find the workflow run that was used to build the artifact + +For more information about how data enters the {% data variables.product.virtual_registry %}, see [AUTOTITLE](/code-security/how-tos/secure-your-supply-chain/establish-provenance-and-integrity/upload-linked-artifacts). + +## Exporting artifact metadata + +To export metadata in bulk for an audit, use the [List artifact deployment records](/rest/orgs/artifact-metadata#list-artifact-deployment-records) and [List artifact storage records](/rest/orgs/artifact-metadata#list-artifact-storage-records) endpoints of the artifact metadata API. diff --git a/content/code-security/tutorials/secure-your-organization/prioritize-alerts-in-production-code.md b/content/code-security/tutorials/secure-your-organization/prioritize-alerts-in-production-code.md index 793e05006665..010aceb5701e 100644 --- a/content/code-security/tutorials/secure-your-organization/prioritize-alerts-in-production-code.md +++ b/content/code-security/tutorials/secure-your-organization/prioritize-alerts-in-production-code.md @@ -18,44 +18,22 @@ redirect_from: - /code-security/tutorials/secure-your-organization/alerts-in-production-code --- -{% data reusables.security.production-context-mdc-preview %} - -## Prioritizing alerts using production context - Application Security (AppSec) managers are often overwhelmed by a high volume of alerts, many of which may not represent real risk because the affected code never makes it to production. By associating production context with your alerts, you can filter and prioritize vulnerabilities that impact artifacts actually approved for production environments. This enables your team to focus remediation efforts on the vulnerabilities that matter most, reducing noise and improving your security posture. -## Associating production context with alerts - -{% data variables.product.github %} enables you to provide production context for {% data variables.product.prodname_dependabot %} and {% data variables.product.prodname_code_scanning %} alerts using the REST API: - -* [Storage Record](/rest/orgs/artifact-metadata#create-artifact-metadata-storage-record) -* [Deployment Record](/rest/orgs/artifact-metadata#create-an-artifact-deployment-record) - -### Storage Record API - -This API allows package registries or GitOps workflows to send artifact lifecycle data to {% data variables.product.github %}. You should configure your system to call the endpoint whenever an artifact is promoted to a production-approved package repository. - -{% data variables.product.github %} processes this metadata and uses it to power new alert filters, such as `artifact-registry-url` and `artifact-registry`. For more information, see [Create artifact metadata storage record](/rest/orgs/artifact-metadata#create-artifact-metadata-storage-record) in the REST API documentation. - -> [!TIP] -> If you use JFrog Artifactory, you do not need to perform any custom integration. Artifactory natively integrates with the Storage Record API. You only need to enable the integration in your Artifactory settings, and Artifactory will automatically emit production promotion events to {% data variables.product.github %}. For setup instructions, see [JFrog and GitHub Integration: JFrog for {% data variables.product.github %} {% data variables.product.prodname_dependabot %}](https://jfrog.com/help/r/jfrog-and-github-integration-guide/jfrog-for-github-dependabot) in the JFrog documentation. - -### Deployment Record API - -This API allows systems to send deployment data for a specific artifact to {% data variables.product.github %}, such as its name, digest, environments, cluster, and deployment. +## 1. Associate artifacts with production context -{% data variables.product.github %} processes this metadata and uses it to power new alert filters, such as `has:deployment` and `runtime-risk`. For more information, see [Create an artifact deployment record](/rest/orgs/artifact-metadata#create-an-artifact-deployment-record) in the REST API documentation. +{% data variables.product.github %}'s {% data variables.product.virtual_registry %} allows you to provide production context for your company's builds using the REST API or a partner integration. Teams can then use this context to prioritize {% data variables.product.prodname_dependabot %} and {% data variables.product.prodname_code_scanning %} alerts. For more information, see [AUTOTITLE](/code-security/concepts/supply-chain-security/linked-artifacts). -> [!TIP] -> If you use {% data variables.product.prodname_mdc_definition %} and connect your instance to a {% data variables.product.github %} organization, {% data variables.product.prodname_mdc %} will automatically send deployment and runtime data to {% data variables.product.github %}. For more information, see [Quick Start: Connect your {% data variables.product.github %} Environment to {% data variables.product.prodname_microsoft_defender %}](https://learn.microsoft.com/en-us/azure/defender-for-cloud/quickstart-onboard-github) in the documentation for {% data variables.product.prodname_mdc %}. +To provide production context, you should configure your system to: -## Enable and use production context for alert prioritization +* Update **storage records** in the {% data variables.product.virtual_registry %} whenever an artifact is promoted to a production-approved package repository. +* Update **deployment records** when an artifact is deployed to a production environment. -### 1. Detect and report production artifact promotions and deployments +{% data variables.product.github %} processes this metadata and uses it to power alert filters, such as `artifact-registry-url` and `artifact-registry` from storage records, and `has:deployment` and `runtime-risk` from deployment records. -In your CI/CD or GitOps workflow, whenever an artifact is promoted to a production-approved package repository, call the Storage Record API to send the artifact's metadata to {% data variables.product.github %}. Whenever an artifact is deployed to production, call the Deployment Record API to send additional metadata for the artifact to {% data variables.product.github %}. +For more information on updating records, see [AUTOTITLE](/code-security/how-tos/secure-your-supply-chain/establish-provenance-and-integrity/upload-linked-artifacts). -### 2. Use production context filters +## 2. Use production context filters Production context filters are made available in alert views and security campaign views under the **Security** tab. @@ -91,7 +69,7 @@ You can also combine these production context filters with other filters, such a epss > 0.5 AND artifact-registry-url:my-registry.example.com ``` -### 3. Remediate alerts in production code +## 3. Remediate alerts in production code Now you have identified the alerts that put your production code at risk of exploitation, you need to remediate them as a matter of urgency. Where possible use automation to lower the barrier to remediation. diff --git a/content/copilot/how-tos/configure-custom-instructions/add-repository-instructions.md b/content/copilot/how-tos/configure-custom-instructions/add-repository-instructions.md index 924658ba75f3..d0c46bee7663 100644 --- a/content/copilot/how-tos/configure-custom-instructions/add-repository-instructions.md +++ b/content/copilot/how-tos/configure-custom-instructions/add-repository-instructions.md @@ -17,6 +17,8 @@ category: - Configure Copilot --- + + {% webui %} This version of this article is for using repository custom instructions on the {% data variables.product.github %} website. Click the tabs above for information on using custom instructions in other environments. @@ -25,293 +27,10 @@ This version of this article is for using repository custom instructions on the {% data reusables.copilot.repository-custom-instructions-prerequisites %} -{% endwebui %} - -{% vscode %} - -This version of this article is for using repository custom instructions and prompt files in {% data variables.product.prodname_vscode_shortname %}. Click the tabs above for instructions on using custom instructions in other environments. - -{% data reusables.copilot.repository-custom-instructions-about %} - -{% data reusables.copilot.repository-custom-instructions-prerequisites %} - -{% endvscode %} - -{% visualstudio %} - -This version of this article is for using repository custom instructions and prompt files in {% data variables.product.prodname_vs %}. Click the tabs above for instructions on using custom instructions in other environments. - -{% data reusables.copilot.repository-custom-instructions-about %} - -{% data reusables.copilot.repository-custom-instructions-prerequisites %} - -{% endvisualstudio %} - -{% jetbrains %} - -This version of this article is for using repository custom instructions in JetBrains IDEs. Click the tabs above for instructions on using custom instructions in other environments. - -{% data reusables.copilot.repository-custom-instructions-about %} - -{% data reusables.copilot.repository-custom-instructions-prerequisites %} - -{% endjetbrains %} - -{% xcode %} - -This version of this article is for using repository custom instructions in Xcode. Click the tabs above for instructions on using custom instructions in other environments. - -{% data reusables.copilot.repository-custom-instructions-about %} - -{% data reusables.copilot.repository-custom-instructions-prerequisites %} - -{% endxcode %} - -{% copilotcli %} - -This version of this article is for using repository custom instructions with the {% data variables.product.prodname_copilot %} CLI. Click the tabs above for instructions on using custom instructions in other environments. - -{% data reusables.copilot.repository-custom-instructions-prerequisites %} - -{% endcopilotcli %} - -{% eclipse %} - -> [!NOTE] This feature is currently in {% data variables.release-phases.public_preview %} and is subject to change. - -This version of this article is for using repository custom instructions in Eclipse. Click the tabs above for instructions on using custom instructions in other environments. - -{% data reusables.copilot.repository-custom-instructions-about %} - -{% data reusables.copilot.repository-custom-instructions-prerequisites %} - -{% endeclipse %} - -{% webui %} - -* Your personal choice of whether to use custom instructions must be set to enabled. This is enabled by default. See [Enabling or disabling repository custom instructions](#enabling-or-disabling-repository-custom-instructions) later in this article. - -{% endwebui %} - -{% vscode %} - -* Custom instructions must be enabled. This feature is enabled by default. See [Enabling or disabling repository custom instructions](#enabling-or-disabling-repository-custom-instructions-1) later in this article. - -{% endvscode %} - -{% visualstudio %} - -* The **Enable custom instructions...** option must be enabled in your settings. This is enabled by default. See [Enabling or disabling repository custom instructions](#enabling-or-disabling-repository-custom-instructions-1) later in this article. - -{% endvisualstudio %} - -{% jetbrains %} - -* The latest version of the {% data variables.product.prodname_copilot_short %} extension must be installed in your JetBrains IDE. - -{% endjetbrains %} - -{% xcode %} - -* The latest version of the {% data variables.product.prodname_copilot_short %} extension must be installed in Xcode. - -{% endxcode %} - -{% eclipse %} - -* The latest version of the {% data variables.product.prodname_copilot_short %} extension must be installed in Eclipse. - -{% endeclipse %} +* For {% data variables.copilot.copilot_code-review_short %}, your personal choice of whether to use custom instructions must be set to enabled. This is enabled by default. See [Enabling or disabling repository custom instructions](#enabling-or-disabling-custom-instructions-for-copilot-code-review) later in this article. ## Creating custom instructions -{% jetbrains %} - -JetBrains IDEs support a single `.github/copilot-instructions.md` custom instructions file stored in the repository, and a locally stored `global-copilot-instructions.md` file. - -You can create the `.github/copilot-instructions.md` file in your repository using the {% data variables.product.prodname_copilot_short %} settings page, or you can create the file manually. - -Whitespace between instructions is ignored, so the instructions can be written as a single paragraph, each on a new line, or separated by blank lines for legibility. - -### Using the settings page - -{% data reusables.copilot.jetbrains-settings %} -{% data reusables.copilot.jetbrains-tools %} -1. Under "{% data variables.product.prodname_copilot_short %} Instructions", click **Workspace** or **Global** to choose whether the custom instructions apply to the current workspace or all workspaces. - -### Manually creating a workspace custom instructions file - -1. In the root of your repository, create a file named `.github/copilot-instructions.md`. - - Create the `.github` directory if it does not already exist. - -1. Add natural language instructions to the file, in Markdown format. - -Once saved, these instructions will apply to the current workspace in JetBrains IDEs that you open with {% data variables.product.prodname_copilot_short %} enabled. - -### Manually creating a global custom instructions file - -To apply the same instructions across all workspaces in JetBrains IDEs, you can create a global custom instructions file on your local machine. - -1. Open your file explorer or terminal. -1. Navigate to the appropriate location for your operating system: - - * **macOS**: - `/Users/YOUR-USERNAME/.config/github-copilot/intellij/` - * **Windows**: - `C:\Users\YOUR-USERNAME\AppData\Local\github-copilot\intellij\` - -1. Create a file named `global-copilot-instructions.md` in that directory. -1. Add your custom instructions in natural language, using Markdown format. - -Once saved, these instructions will apply globally across all workspaces in JetBrains IDEs that you open with {% data variables.product.prodname_copilot_short %} enabled. - -{% endjetbrains %} - -{% xcode %} - -Xcode supports a single `.github/copilot-instructions.md` custom instructions file stored in the repository. - -You can create a custom instructions file in your repository via the {% data variables.product.prodname_copilot_short %} settings page. - -Whitespace between instructions is ignored, so the instructions can be written as a single paragraph, each on a new line, or separated by blank lines for legibility. - -1. Open the {% data variables.product.prodname_copilot %} for Xcode application. -1. At the top of the application window, under **Settings**, click **Advanced**. -1. To the right of "Custom Instructions", click **Current Workspace** or **Global** to choose whether the custom instructions apply to the current workspace or all workspaces. - -{% endxcode %} - -{% eclipse %} - -Eclipse supports two types of repository custom instructions: workspace and project custom instructions. - -To create a workspace custom instructions file, you can use the {% data variables.product.prodname_copilot_short %} settings page. To create a project custom instructions file, you can create the file manually in the project directory. - -Whitespace between instructions is ignored, so the instructions can be written as a single paragraph, each on a new line, or separated by blank lines for legibility. - -### Creating a workspace custom instructions file - -1. To open the {% data variables.copilot.copilot_chat_short %} panel, click the {% data variables.product.prodname_copilot_short %} icon ({% octicon "copilot" aria-hidden="true" aria-label="copilot" %}) in the status bar at the bottom of Eclipse. -1. From the menu, select "Edit preferences". -1. In the left pane, expand {% data variables.product.prodname_copilot %} and click **Custom Instructions**. -1. Select **Enable workspace instructions**. -1. In the "Workspace" section, under "Set custom instructions to guide {% data variables.product.prodname_copilot_short %}'s code suggestions in this workspace", add natural language instructions to the file, in Markdown format. - -### Creating a project custom instructions file - -1. In the root of your project directory, create a file named `.github/copilot-instructions.md`. -1. Add your custom instructions in natural language, using Markdown format. - -Once saved, these instructions will apply to the current project in Eclipse that you open with {% data variables.product.prodname_copilot_short %} enabled. - -{% endeclipse %} - -{% copilotcli %} - -{% data variables.product.prodname_copilot %} supports three types of repository custom instructions. - -* **Repository-wide custom instructions**, which apply to all requests made in the context of a repository. - - These are specified in a `copilot-instructions.md` file in the `.github` directory of the repository. See [Creating repository-wide custom instructions](#creating-repository-wide-custom-instructions). - -* **Path-specific custom instructions**, which apply to requests made in the context of files that match a specified path. - - These are specified in one or more `NAME.instructions.md` files within or below the `.github/instructions` directory in the repository. See [Creating path-specific custom instructions](#creating-path-specific-custom-instructions). - - If the path you specify matches a file that {% data variables.product.prodname_copilot_short %} is working on, and a repository-wide custom instructions file also exists, then the instructions from both files are used. You should avoid potential conflicts between instructions as {% data variables.product.prodname_copilot_short %}'s choice between conflicting instructions is non-deterministic. - -* **Agent instructions** are used by AI agents. - - {% data reusables.copilot.custom-instructions-agents %} - - Alternatively, you can use a single `CLAUDE.md` or `GEMINI.md` file stored in the root of the repository. - -## Creating repository-wide custom instructions - -1. In the root of your repository, create a file named `.github/copilot-instructions.md`. - - Create the `.github` directory if it does not already exist. - -1. Add natural language instructions to the file, in Markdown format. - - Whitespace between instructions is ignored, so the instructions can be written as a single paragraph, each on a new line, or separated by blank lines for legibility. - -## Creating path-specific custom instructions - -{% data reusables.copilot.custom-instructions-path %} - -{% endcopilotcli %} - -{% vscode %} - -{% data variables.product.prodname_vscode_shortname %} supports three types of repository custom instructions. For details of which {% data variables.product.prodname_copilot %} features support these types of instructions, see [AUTOTITLE](/copilot/concepts/prompting/response-customization?tool=vscode#support-for-repository-custom-instructions-1). - -* **Repository-wide custom instructions**, which apply to all requests made in the context of a repository. - - These are specified in a `copilot-instructions.md` file in the `.github` directory of the repository. See [Creating repository-wide custom instructions](#creating-repository-wide-custom-instructions-1). - -* **Path-specific custom instructions**, which apply to requests made in the context of files that match a specified path. - - These are specified in one or more `NAME.instructions.md` files within or below the `.github/instructions` directory in the repository. See [Creating path-specific custom instructions](#creating-path-specific-custom-instructions-1). - - If the path you specify matches a file that {% data variables.product.prodname_copilot_short %} is working on, and a repository-wide custom instructions file also exists, then the instructions from both files are used. - -* **Agent instructions** are used by AI agents. - - {% data reusables.copilot.custom-instructions-agents %} - - > [!NOTE] - > Support of `AGENTS.md` files outside of the workspace root is currently turned off by default. For details of how to enable this feature, see [Use custom instructions in VS Code](https://code.visualstudio.com/docs/copilot/customization/custom-instructions#_use-an-agentsmd-file) in the {% data variables.product.prodname_vscode_shortname %} documentation. - -## Creating repository-wide custom instructions - -1. In the root of your repository, create a file named `.github/copilot-instructions.md`. - - Create the `.github` directory if it does not already exist. - -1. Add natural language instructions to the file, in Markdown format. - - Whitespace between instructions is ignored, so the instructions can be written as a single paragraph, each on a new line, or separated by blank lines for legibility. - -## Creating path-specific custom instructions - -{% data reusables.copilot.custom-instructions-path %} - -{% endvscode %} - -{% visualstudio %} - -{% data variables.product.prodname_vs %} supports two types of custom instructions. For details of which {% data variables.product.prodname_copilot %} features support these types of instructions, see [AUTOTITLE](/copilot/concepts/prompting/response-customization?tool=visualstudio#support-for-repository-custom-instructions-2). - -* **Repository-wide custom instructions**, which apply to all requests made in the context of a repository. - - These are specified in a `copilot-instructions.md` file in the `.github` directory of the repository. See [Creating repository-wide custom instructions](#creating-repository-wide-custom-instructions-2). - -* **Path-specific custom instructions**, which apply to requests made in the context of files that match a specified path. - - These are specified in one or more `NAME.instructions.md` files within or below the `.github/instructions` directory in the repository. See [Creating path-specific custom instructions](#creating-path-specific-custom-instructions-2). - - If the path you specify matches a file that {% data variables.product.prodname_copilot_short %} is working on, and a repository-wide custom instructions file also exists, then the instructions from both files are used. - -## Creating repository-wide custom instructions - -1. In the root of your repository, create a file named `.github/copilot-instructions.md`. - - Create the `.github` directory if it does not already exist. - -1. Add natural language instructions to the file, in Markdown format. - - Whitespace between instructions is ignored, so the instructions can be written as a single paragraph, each on a new line, or separated by blank lines for legibility. - -## Creating path-specific custom instructions - -{% data reusables.copilot.custom-instructions-path %} - -{% endvisualstudio %} - -{% webui %} - {% data variables.product.prodname_copilot_short %} on {% data variables.product.github %} supports three types of repository custom instructions. For details of which {% data variables.product.prodname_copilot %} features support these types of instructions, see [AUTOTITLE](/copilot/concepts/prompting/response-customization?tool=webui#support-for-repository-custom-instructions). * **Repository-wide custom instructions** apply to all requests made in the context of a repository. @@ -443,98 +162,195 @@ You can create your own custom instructions file from scratch. See [Writing your {% data reusables.copilot.custom-instructions-path %} +{% data reusables.copilot.custom-instructions-note %} + +In {% data variables.copilot.copilot_chat_short %} ([github.com/copilot](https://github.com/copilot)), you can start a conversation that uses repository custom instructions by adding, as an attachment, the repository that contains the instructions file. + +Whenever repository custom instructions are used by {% data variables.copilot.copilot_chat_short %}, the instructions file is added as a reference for the response that's generated. To find out whether repository custom instructions were used, expand the list of references at the top of a chat response in the Chat panel and check whether the `.github/copilot-instructions.md` file is listed. + +![Screenshot of an expanded References list, showing the 'copilot-instructions.md' file highlighted with a dark orange outline.](/assets/images/help/copilot/custom-instructions-ref-in-github.png) + +You can click the reference to open the file. + +> [!NOTE] +> * {% data reusables.copilot.custom-instructions-chat-precedence %} +> * {% data reusables.copilot.custom-instructions-conflict %} + +## Enabling or disabling custom instructions for {% data variables.copilot.copilot_code-review_short %} + +Custom instructions are enabled for {% data variables.copilot.copilot_code-review_short %} by default but you can disable, or re-enable, them in the repository settings on {% data variables.product.prodname_dotcom_the_website %}. This applies to {% data variables.product.prodname_copilot_short %}'s use of custom instructions for all code reviews it performs in this repository. + +{% data reusables.repositories.navigate-to-repo %} +{% data reusables.repositories.sidebar-settings %} +1. In the "Code & automation" section of the sidebar, click **{% octicon "copilot" aria-hidden="true" aria-label="copilot" %} {% data variables.product.prodname_copilot_short %}**, then **Code review**. +1. Toggle the “Use custom instructions when reviewing pull requests” option on or off. + +## Further reading + +* [AUTOTITLE](/copilot/reference/custom-instructions-support) +* [AUTOTITLE](/copilot/tutorials/customization-library/custom-instructions)—a curated collection of examples +* [AUTOTITLE](/copilot/tutorials/use-custom-instructions) + {% endwebui %} -{% note %} + -Did you successfully add a custom instructions file to your repository? + -Yes No +{% vscode %} -{% endnote %} +This version of this article is for using repository custom instructions and prompt files in {% data variables.product.prodname_vscode_shortname %}. Click the tabs above for instructions on using custom instructions in other environments. -## Repository custom instructions in use +{% data reusables.copilot.repository-custom-instructions-about %} -The instructions in the file(s) are available for use by {% data variables.product.prodname_copilot_short %} as soon as you save the file(s). The complete set of instructions will be automatically added to requests that you submit to {% data variables.product.prodname_copilot_short %} in the context of that repository. For example, they are added to the prompt you submit to {% data variables.copilot.copilot_chat_short %}. +{% data reusables.copilot.repository-custom-instructions-prerequisites %} -{% webui %} +* Custom instructions must be enabled. This feature is enabled by default. See [Enabling or disabling repository custom instructions](#enabling-or-disabling-repository-custom-instructions-1) later in this article. -In {% data variables.copilot.copilot_chat_short %} ([github.com/copilot](https://github.com/copilot)), you can start a conversation that uses repository custom instructions by adding, as an attachment, the repository that contains the instructions file. +## Creating custom instructions + +{% vscode %} + +{% data variables.product.prodname_vscode_shortname %} supports three types of repository custom instructions. For details of which {% data variables.product.prodname_copilot %} features support these types of instructions, see [AUTOTITLE](/copilot/concepts/prompting/response-customization?tool=vscode#support-for-repository-custom-instructions-1). + +* **Repository-wide custom instructions**, which apply to all requests made in the context of a repository. + + These are specified in a `copilot-instructions.md` file in the `.github` directory of the repository. See [Creating repository-wide custom instructions](#creating-repository-wide-custom-instructions-1). + +* **Path-specific custom instructions**, which apply to requests made in the context of files that match a specified path. + + These are specified in one or more `NAME.instructions.md` files within or below the `.github/instructions` directory in the repository. See [Creating path-specific custom instructions](#creating-path-specific-custom-instructions-1). + + If the path you specify matches a file that {% data variables.product.prodname_copilot_short %} is working on, and a repository-wide custom instructions file also exists, then the instructions from both files are used. + +* **Agent instructions** are used by AI agents. + + {% data reusables.copilot.custom-instructions-agents %} + + > [!NOTE] + > Support of `AGENTS.md` files outside of the workspace root is currently turned off by default. For details of how to enable this feature, see [Use custom instructions in VS Code](https://code.visualstudio.com/docs/copilot/customization/custom-instructions#_use-an-agentsmd-file) in the {% data variables.product.prodname_vscode_shortname %} documentation. + +## Creating repository-wide custom instructions + +1. In the root of your repository, create a file named `.github/copilot-instructions.md`. + + Create the `.github` directory if it does not already exist. + +1. Add natural language instructions to the file, in Markdown format. + + Whitespace between instructions is ignored, so the instructions can be written as a single paragraph, each on a new line, or separated by blank lines for legibility. + +## Creating path-specific custom instructions + +{% data reusables.copilot.custom-instructions-path %} + +{% endvscode %} + +{% data reusables.copilot.custom-instructions-note %} + +{% data reusables.copilot.custom-instructions-reference %} + +![Screenshot of an expanded References list, showing the 'copilot-instructions.md' file highlighted with a dark orange outline.](/assets/images/help/copilot/custom-instructions-vscode.png) + +{% data reusables.copilot.custom-instructions-enabling %} + +1. Open the Setting editor by using the keyboard shortcut Command+, (Mac) / Ctrl+, (Linux/Windows). +1. Type `instruction file` in the search box. +1. Select or clear the checkbox under **Code Generation: Use Instruction Files**. + +{% data reusables.copilot.custom-instructions-enabling-for-ccr %} + +## Enabling and using prompt files + +{% data reusables.copilot.prompt-files-preview-note %} + +Prompt files let you build and share reusable prompt instructions with additional context. A prompt file is a Markdown file, stored in your workspace, that mimics the existing format of writing prompts in {% data variables.copilot.copilot_chat_short %} (for example, `Rewrite #file:x.ts`). You can have multiple prompt files in your workspace, each of which defines a prompt for a different purpose. + +### Enabling prompt files + +To enable prompt files, configure the workspace settings. + +1. Open the command palette by pressing Ctrl+Shift+P (Windows/Linux) / Command+Shift+P (Mac). +1. Type "Open Workspace Settings (JSON)" and select the option that's displayed. +1. In the `settings.json` file, add `"chat.promptFiles": true` to enable the `.github/prompts` folder as the location for prompt files. This folder will be created if it does not already exist. + +### Creating prompt files + +1. Open the command palette by pressing Ctrl+Shift+P (Windows/Linux) / Command+Shift+P (Mac). +1. Type "prompt" and select **Chat: Create Prompt**. +1. Enter a name for the prompt file, excluding the `.prompt.md` file name extension. The name can contain alphanumeric characters and spaces and should describe the purpose of the prompt information the file will contain. +1. Write the prompt instructions, using Markdown formatting. -Whenever repository custom instructions are used by {% data variables.copilot.copilot_chat_short %}, the instructions file is added as a reference for the response that's generated. To find out whether repository custom instructions were used, expand the list of references at the top of a chat response in the Chat panel and check whether the `.github/copilot-instructions.md` file is listed. + You can reference other files in the workspace by using Markdown links—for example, `[index](../../web/index.ts)`—or by using the `#file:../../web/index.ts` syntax. Paths are relative to the prompt file. Referencing other files allows you to provide additional context, such as API specifications or product documentation. -![Screenshot of an expanded References list, showing the 'copilot-instructions.md' file highlighted with a dark orange outline.](/assets/images/help/copilot/custom-instructions-ref-in-github.png) +### Using prompt files -You can click the reference to open the file. +1. At the bottom of the {% data variables.copilot.copilot_chat_short %} view, click the **Attach context** icon ({% octicon "paperclip" aria-hidden="true" aria-label="paperclip" %}). +1. In the dropdown menu, click **Prompt...** and choose the prompt file you want to use. +1. Optionally, attach additional files, including prompt files, to provide more context. +1. Optionally, type additional information in the chat prompt box. -> [!NOTE] -> * {% data reusables.copilot.custom-instructions-chat-precedence %} -> * {% data reusables.copilot.custom-instructions-conflict %} + Whether you need to do this or not depends on the contents of the prompt you are using. -{% endwebui %} +1. Submit the chat prompt. -{% vscode %} +For more information about prompt files, see [Use prompt files in {% data variables.product.prodname_vscode %}](https://code.visualstudio.com/docs/copilot/customization/prompt-files) in the {% data variables.product.prodname_vscode %} documentation. -{% data reusables.copilot.custom-instructions-reference %} +## Further reading -![Screenshot of an expanded References list, showing the 'copilot-instructions.md' file highlighted with a dark orange outline.](/assets/images/help/copilot/custom-instructions-vscode.png) +* [AUTOTITLE](/copilot/reference/custom-instructions-support) +* [AUTOTITLE](/copilot/tutorials/customization-library)—a curated collection of examples +* [AUTOTITLE](/copilot/tutorials/use-custom-instructions) {% endvscode %} -{% visualstudio %} - -{% data reusables.copilot.custom-instructions-reference %} + -![Screenshot of the References popup, showing the 'copilot-instructions.md' file highlighted with a dark orange outline.](/assets/images/help/copilot/custom-instruction-ref-visual-studio.png) + -{% endvisualstudio %} +{% visualstudio %} -{% jetbrains %} +This version of this article is for using repository custom instructions and prompt files in {% data variables.product.prodname_vs %}. Click the tabs above for instructions on using custom instructions in other environments. -{% data reusables.copilot.custom-instructions-reference %} +{% data reusables.copilot.repository-custom-instructions-about %} -{% endjetbrains %} +{% data reusables.copilot.repository-custom-instructions-prerequisites %} -{% xcode %} +* The **Enable custom instructions...** option must be enabled in your settings. This is enabled by default. See [Enabling or disabling repository custom instructions](#enabling-or-disabling-repository-custom-instructions-1) later in this article. -{% data reusables.copilot.custom-instructions-reference %} +## Creating custom instructions -## Further reading +{% data variables.product.prodname_vs %} supports two types of custom instructions. For details of which {% data variables.product.prodname_copilot %} features support these types of instructions, see [AUTOTITLE](/copilot/concepts/prompting/response-customization?tool=visualstudio#support-for-repository-custom-instructions-2). -* [AUTOTITLE](/copilot/tutorials/customization-library/custom-instructions)—a curated collection of examples +* **Repository-wide custom instructions**, which apply to all requests made in the context of a repository. -{% endxcode %} + These are specified in a `copilot-instructions.md` file in the `.github` directory of the repository. See [Creating repository-wide custom instructions](#creating-repository-wide-custom-instructions-2). -{% webui %} +* **Path-specific custom instructions**, which apply to requests made in the context of files that match a specified path. -## Enabling or disabling custom instructions for {% data variables.copilot.copilot_code-review_short %} + These are specified in one or more `NAME.instructions.md` files within or below the `.github/instructions` directory in the repository. See [Creating path-specific custom instructions](#creating-path-specific-custom-instructions-2). -Custom instructions are enabled for {% data variables.copilot.copilot_code-review_short %} by default but you can disable, or re-enable, them in the repository settings on {% data variables.product.prodname_dotcom_the_website %}. This applies to {% data variables.product.prodname_copilot_short %}'s use of custom instructions for all code reviews it performs in this repository. + If the path you specify matches a file that {% data variables.product.prodname_copilot_short %} is working on, and a repository-wide custom instructions file also exists, then the instructions from both files are used. -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -1. In the "Code & automation" section of the sidebar, click **{% octicon "copilot" aria-hidden="true" aria-label="copilot" %} {% data variables.product.prodname_copilot_short %}**, then **Code review**. -1. Toggle the “Use custom instructions when reviewing pull requests” option on or off. +## Creating repository-wide custom instructions -## Further reading +1. In the root of your repository, create a file named `.github/copilot-instructions.md`. -* [AUTOTITLE](/copilot/tutorials/customization-library/custom-instructions)—a curated collection of examples + Create the `.github` directory if it does not already exist. -{% endwebui %} +1. Add natural language instructions to the file, in Markdown format. -{% vscode %} + Whitespace between instructions is ignored, so the instructions can be written as a single paragraph, each on a new line, or separated by blank lines for legibility. -{% data reusables.copilot.custom-instructions-enabling %} +## Creating path-specific custom instructions -1. Open the Setting editor by using the keyboard shortcut Command+, (Mac) / Ctrl+, (Linux/Windows). -1. Type `instruction file` in the search box. -1. Select or clear the checkbox under **Code Generation: Use Instruction Files**. +{% data reusables.copilot.custom-instructions-path %} -{% data reusables.copilot.custom-instructions-enabling-for-ccr %} +{% data reusables.copilot.custom-instructions-note %} -{% endvscode %} +{% data reusables.copilot.custom-instructions-reference %} -{% visualstudio %} +![Screenshot of the References popup, showing the 'copilot-instructions.md' file highlighted with a dark orange outline.](/assets/images/help/copilot/custom-instruction-ref-visual-studio.png) {% data reusables.copilot.custom-instructions-enabling %} @@ -566,55 +382,70 @@ For more information about prompt files, see [Use prompt files in {% data variab ## Further reading +* [AUTOTITLE](/copilot/reference/custom-instructions-support) * [AUTOTITLE](/copilot/tutorials/customization-library)—a curated collection of examples +* [AUTOTITLE](/copilot/tutorials/use-custom-instructions) {% endvisualstudio %} -{% vscode %} + -## Enabling and using prompt files + -{% data reusables.copilot.prompt-files-preview-note %} +{% jetbrains %} -Prompt files let you build and share reusable prompt instructions with additional context. A prompt file is a Markdown file, stored in your workspace, that mimics the existing format of writing prompts in {% data variables.copilot.copilot_chat_short %} (for example, `Rewrite #file:x.ts`). You can have multiple prompt files in your workspace, each of which defines a prompt for a different purpose. +This version of this article is for using repository custom instructions in JetBrains IDEs. Click the tabs above for instructions on using custom instructions in other environments. -### Enabling prompt files +{% data reusables.copilot.repository-custom-instructions-about %} -To enable prompt files, configure the workspace settings. +{% data reusables.copilot.repository-custom-instructions-prerequisites %} -1. Open the command palette by pressing Ctrl+Shift+P (Windows/Linux) / Command+Shift+P (Mac). -1. Type "Open Workspace Settings (JSON)" and select the option that's displayed. -1. In the `settings.json` file, add `"chat.promptFiles": true` to enable the `.github/prompts` folder as the location for prompt files. This folder will be created if it does not already exist. +* The latest version of the {% data variables.product.prodname_copilot_short %} extension must be installed in your JetBrains IDE. -### Creating prompt files +## Creating custom instructions -1. Open the command palette by pressing Ctrl+Shift+P (Windows/Linux) / Command+Shift+P (Mac). -1. Type "prompt" and select **Chat: Create Prompt**. -1. Enter a name for the prompt file, excluding the `.prompt.md` file name extension. The name can contain alphanumeric characters and spaces and should describe the purpose of the prompt information the file will contain. -1. Write the prompt instructions, using Markdown formatting. +JetBrains IDEs support a single `.github/copilot-instructions.md` custom instructions file stored in the repository, and a locally stored `global-copilot-instructions.md` file. - You can reference other files in the workspace by using Markdown links—for example, `[index](../../web/index.ts)`—or by using the `#file:../../web/index.ts` syntax. Paths are relative to the prompt file. Referencing other files allows you to provide additional context, such as API specifications or product documentation. +You can create the `.github/copilot-instructions.md` file in your repository using the {% data variables.product.prodname_copilot_short %} settings page, or you can create the file manually. -### Using prompt files +Whitespace between instructions is ignored, so the instructions can be written as a single paragraph, each on a new line, or separated by blank lines for legibility. -1. At the bottom of the {% data variables.copilot.copilot_chat_short %} view, click the **Attach context** icon ({% octicon "paperclip" aria-hidden="true" aria-label="paperclip" %}). -1. In the dropdown menu, click **Prompt...** and choose the prompt file you want to use. -1. Optionally, attach additional files, including prompt files, to provide more context. -1. Optionally, type additional information in the chat prompt box. +### Using the settings page - Whether you need to do this or not depends on the contents of the prompt you are using. +{% data reusables.copilot.jetbrains-settings %} +{% data reusables.copilot.jetbrains-tools %} +1. Under "{% data variables.product.prodname_copilot_short %} Instructions", click **Workspace** or **Global** to choose whether the custom instructions apply to the current workspace or all workspaces. -1. Submit the chat prompt. +### Manually creating a workspace custom instructions file -For more information about prompt files, see [Use prompt files in {% data variables.product.prodname_vscode %}](https://code.visualstudio.com/docs/copilot/customization/prompt-files) in the {% data variables.product.prodname_vscode %} documentation. +1. In the root of your repository, create a file named `.github/copilot-instructions.md`. -## Further reading + Create the `.github` directory if it does not already exist. -* [AUTOTITLE](/copilot/tutorials/customization-library)—a curated collection of examples +1. Add natural language instructions to the file, in Markdown format. -{% endvscode %} +Once saved, these instructions will apply to the current workspace in JetBrains IDEs that you open with {% data variables.product.prodname_copilot_short %} enabled. -{% jetbrains %} +### Manually creating a global custom instructions file + +To apply the same instructions across all workspaces in JetBrains IDEs, you can create a global custom instructions file on your local machine. + +1. Open your file explorer or terminal. +1. Navigate to the appropriate location for your operating system: + + * **macOS**: + `/Users/YOUR-USERNAME/.config/github-copilot/intellij/` + * **Windows**: + `C:\Users\YOUR-USERNAME\AppData\Local\github-copilot\intellij\` + +1. Create a file named `global-copilot-instructions.md` in that directory. +1. Add your custom instructions in natural language, using Markdown format. + +Once saved, these instructions will apply globally across all workspaces in JetBrains IDEs that you open with {% data variables.product.prodname_copilot_short %} enabled. + +{% data reusables.copilot.custom-instructions-note %} + +{% data reusables.copilot.custom-instructions-reference %} ## Using prompt files @@ -654,23 +485,146 @@ Once prompt files are saved, their instructions will apply to the current worksp ## Further reading -* [AUTOTITLE](/copilot/tutorials/customization-library) +* [AUTOTITLE](/copilot/reference/custom-instructions-support) +* [AUTOTITLE](/copilot/tutorials/customization-library)—a curated collection of examples +* [AUTOTITLE](/copilot/tutorials/use-custom-instructions) {% endjetbrains %} -{% eclipse %} + + + + +{% xcode %} + +This version of this article is for using repository custom instructions in Xcode. Click the tabs above for instructions on using custom instructions in other environments. + +{% data reusables.copilot.repository-custom-instructions-about %} + +{% data reusables.copilot.repository-custom-instructions-prerequisites %} + +* The latest version of the {% data variables.product.prodname_copilot_short %} extension must be installed in Xcode. + +## Creating custom instructions + +Xcode supports a single `.github/copilot-instructions.md` custom instructions file stored in the repository. + +You can create a custom instructions file in your repository via the {% data variables.product.prodname_copilot_short %} settings page. + +Whitespace between instructions is ignored, so the instructions can be written as a single paragraph, each on a new line, or separated by blank lines for legibility. + +1. Open the {% data variables.product.prodname_copilot %} for Xcode application. +1. At the top of the application window, under **Settings**, click **Advanced**. +1. To the right of "Custom Instructions", click **Current Workspace** or **Global** to choose whether the custom instructions apply to the current workspace or all workspaces. + +{% data reusables.copilot.custom-instructions-note %} + +{% data reusables.copilot.custom-instructions-reference %} ## Further reading +* [AUTOTITLE](/copilot/reference/custom-instructions-support) * [AUTOTITLE](/copilot/tutorials/customization-library/custom-instructions)—a curated collection of examples +* [AUTOTITLE](/copilot/tutorials/use-custom-instructions) -{% endeclipse %} +{% endxcode %} + + + + {% copilotcli %} +This version of this article is for using repository custom instructions with the {% data variables.product.prodname_copilot %} CLI. Click the tabs above for instructions on using custom instructions in other environments. + +## Creating custom instructions + +{% data variables.product.prodname_copilot %} supports three types of repository custom instructions. + +* **Repository-wide custom instructions**, which apply to all requests made in the context of a repository. + + These are specified in a `copilot-instructions.md` file in the `.github` directory of the repository. See [Creating repository-wide custom instructions](#creating-repository-wide-custom-instructions). + +* **Path-specific custom instructions**, which apply to requests made in the context of files that match a specified path. + + These are specified in one or more `NAME.instructions.md` files within or below the `.github/instructions` directory in the repository. See [Creating path-specific custom instructions](#creating-path-specific-custom-instructions). + + If the path you specify matches a file that {% data variables.product.prodname_copilot_short %} is working on, and a repository-wide custom instructions file also exists, then the instructions from both files are used. You should avoid potential conflicts between instructions as {% data variables.product.prodname_copilot_short %}'s choice between conflicting instructions is non-deterministic. + +* **Agent instructions** are used by AI agents. + + {% data reusables.copilot.custom-instructions-agents %} + + Alternatively, you can use a single `CLAUDE.md` or `GEMINI.md` file stored in the root of the repository. + +## Creating repository-wide custom instructions + +1. In the root of your repository, create a file named `.github/copilot-instructions.md`. + + Create the `.github` directory if it does not already exist. + +1. Add natural language instructions to the file, in Markdown format. + + Whitespace between instructions is ignored, so the instructions can be written as a single paragraph, each on a new line, or separated by blank lines for legibility. + +## Creating path-specific custom instructions + +{% data reusables.copilot.custom-instructions-path %} + +{% data reusables.copilot.custom-instructions-note %} + ## Further reading -* [AUTOTITLE](/copilot/tutorials/use-custom-instructions) +* [AUTOTITLE](/copilot/reference/custom-instructions-support) * [AUTOTITLE](/copilot/tutorials/customization-library/custom-instructions)—a curated collection of examples +* [AUTOTITLE](/copilot/tutorials/use-custom-instructions) {% endcopilotcli %} + + + + + +{% eclipse %} + +> [!NOTE] This feature is currently in {% data variables.release-phases.public_preview %} and is subject to change. + +This version of this article is for using repository custom instructions in Eclipse. Click the tabs above for instructions on using custom instructions in other environments. + +{% data reusables.copilot.repository-custom-instructions-about %} + +{% data reusables.copilot.repository-custom-instructions-prerequisites %} + +* The latest version of the {% data variables.product.prodname_copilot_short %} extension must be installed in Eclipse. + +## Creating custom instructions + +Eclipse supports two types of repository custom instructions: workspace and project custom instructions. + +To create a workspace custom instructions file, you can use the {% data variables.product.prodname_copilot_short %} settings page. To create a project custom instructions file, you can create the file manually in the project directory. + +Whitespace between instructions is ignored, so the instructions can be written as a single paragraph, each on a new line, or separated by blank lines for legibility. + +### Creating a workspace custom instructions file + +1. To open the {% data variables.copilot.copilot_chat_short %} panel, click the {% data variables.product.prodname_copilot_short %} icon ({% octicon "copilot" aria-hidden="true" aria-label="copilot" %}) in the status bar at the bottom of Eclipse. +1. From the menu, select "Edit preferences". +1. In the left pane, expand {% data variables.product.prodname_copilot %} and click **Custom Instructions**. +1. Select **Enable workspace instructions**. +1. In the "Workspace" section, under "Set custom instructions to guide {% data variables.product.prodname_copilot_short %}'s code suggestions in this workspace", add natural language instructions to the file, in Markdown format. + +### Creating a project custom instructions file + +1. In the root of your project directory, create a file named `.github/copilot-instructions.md`. +1. Add your custom instructions in natural language, using Markdown format. + +Once saved, these instructions will apply to the current project in Eclipse that you open with {% data variables.product.prodname_copilot_short %} enabled. + +{% data reusables.copilot.custom-instructions-note %} + +## Further reading + +* [AUTOTITLE](/copilot/reference/custom-instructions-support) +* [AUTOTITLE](/copilot/tutorials/customization-library/custom-instructions)—a curated collection of examples + +{% endeclipse %} diff --git a/content/packages/learn-github-packages/introduction-to-github-packages.md b/content/packages/learn-github-packages/introduction-to-github-packages.md index 95b39b5b0422..ea9e92ee35e3 100644 --- a/content/packages/learn-github-packages/introduction-to-github-packages.md +++ b/content/packages/learn-github-packages/introduction-to-github-packages.md @@ -43,6 +43,25 @@ The permissions for a package are either inherited from the repository where the {% data reusables.package_registry.public-or-private-packages %} +{% ifversion virtual-registry %} + +## About linked artifacts for organizations + +The {% data variables.product.virtual_registry %} is an alternative view that you can also access in the "Packages" section of an organization's settings. + +Like {% data variables.product.prodname_registry %}, the {% data variables.product.virtual_registry %} allows you to collect information about your organization's builds in a single place. Teams can use the {% data variables.product.virtual_registry %} to find an artifact's source code, build details, and deployment history. + +Unlike {% data variables.product.prodname_registry %}, the {% data variables.product.virtual_registry %} does **not** host the package or image files themselves. Instead, it provides an authoritative source for the metadata associated with each package or image. + +Your organization may benefit from using the {% data variables.product.virtual_registry %} either: + +* **Alongside** {% data variables.product.prodname_registry %}, as an complementary view focused on the compliance and security aspects of package consumption +* **As an alternative to** {% data variables.product.prodname_registry %}, allowing you to store your packages on an external registry of your choice while maintaining visibility of the packages on {% data variables.product.github %} + +For more information, see [AUTOTITLE](/code-security/concepts/supply-chain-security/linked-artifacts). + +{% endif %} + {% ifversion fpt or ghec %} ## About billing for {% data variables.product.prodname_registry %} diff --git a/content/rest/orgs/artifact-metadata.md b/content/rest/orgs/artifact-metadata.md index 079d6190e59f..cd3d7533bd70 100644 --- a/content/rest/orgs/artifact-metadata.md +++ b/content/rest/orgs/artifact-metadata.md @@ -11,6 +11,6 @@ autogenerated: rest allowTitleToDifferFromFilename: true --- -When you view {% data variables.product.prodname_dependabot %} or {% data variables.product.prodname_code_scanning %} alerts for an organization, you can use artifact metadata to filter and prioritize alerts, see [AUTOTITLE](/code-security/securing-your-organization/understanding-your-organizations-exposure-to-vulnerabilities/alerts-in-production-code). +You can use these endpoints to upload storage and deployment records for software that your organization builds with {% data variables.product.prodname_actions %}. The records are displayed on the organization's {% data variables.product.virtual_registry %}. See [AUTOTITLE](/code-security/concepts/supply-chain-security/linked-artifacts). diff --git a/data/features/dependabot-auto-triage-rules.yml b/data/features/dependabot-auto-triage-rules.yml deleted file mode 100644 index b11f1f6dcf8a..000000000000 --- a/data/features/dependabot-auto-triage-rules.yml +++ /dev/null @@ -1,9 +0,0 @@ -# References: -# Issue #10052 - Safe auto-dismissals for Dependabot alerts (low impact npm devDependencies) [Public Beta] -# Issue #10089 - Alert rules: user-configured dismiss rules for Dependabot alerts -# Issue #10068 - Dependabot alert custom rules updates (option to create a PR, org level rules) - -versions: - fpt: '*' - ghec: '*' - ghes: '>3.11' diff --git a/data/features/push-protection-delegated-bypass.yml b/data/features/push-protection-delegated-bypass.yml deleted file mode 100644 index 9f01b22087b7..000000000000 --- a/data/features/push-protection-delegated-bypass.yml +++ /dev/null @@ -1,6 +0,0 @@ -# Issue 10362 - Push protection delegated bypass -# Ref 17108 Advanced Security available to Team plans -versions: - fpt: '*' - ghec: '*' - ghes: '>=3.14' diff --git a/data/features/secret-scanning-non-provider-patterns.yml b/data/features/secret-scanning-non-provider-patterns.yml deleted file mode 100644 index 5f943660505e..000000000000 --- a/data/features/secret-scanning-non-provider-patterns.yml +++ /dev/null @@ -1,7 +0,0 @@ -# Reference: #10154. -# Secret scanning for non-provider patterns [Public Beta] -# Ref 17108 Advanced Security available to Team plans -versions: - fpt: '*' - ghec: '*' - ghes: '>3.11' diff --git a/data/features/security-configurations-ga.yml b/data/features/security-configurations-ga.yml deleted file mode 100644 index 0ce24ebcb38d..000000000000 --- a/data/features/security-configurations-ga.yml +++ /dev/null @@ -1,6 +0,0 @@ -# Reference: #13288 -# Documentation for security configurations and global settings. -versions: - fpt: '*' - ghec: '*' - ghes: '>3.14' diff --git a/data/features/virtual-registry.yml b/data/features/virtual-registry.yml new file mode 100644 index 000000000000..01fe83711095 --- /dev/null +++ b/data/features/virtual-registry.yml @@ -0,0 +1,5 @@ +# The virtual registry or "Linked artifacts" page. Ref: 20118 + +versions: + fpt: '*' + ghec: '*' diff --git a/data/release-notes/enterprise-server/3-14/22.yml b/data/release-notes/enterprise-server/3-14/22.yml index f1338b503457..91a829021df0 100644 --- a/data/release-notes/enterprise-server/3-14/22.yml +++ b/data/release-notes/enterprise-server/3-14/22.yml @@ -1,8 +1,5 @@ date: '2026-01-06' sections: - security_fixes: - - | - Developers and administrators interacting with filter suggestions in the UI will see suggestion text rendered as plain text by default. Previously, display names could be shown as raw HTML, which risked displaying unintended formatting or unsafe content. bugs: - | On instances with GitHub Actions enabled, when administrators deleted a self-hosted runner from the service, the runner process continued running on the host and did not exit automatically. diff --git a/data/release-notes/enterprise-server/3-15/17.yml b/data/release-notes/enterprise-server/3-15/17.yml index dc36b13d3ab1..610c1e93fd77 100644 --- a/data/release-notes/enterprise-server/3-15/17.yml +++ b/data/release-notes/enterprise-server/3-15/17.yml @@ -1,8 +1,5 @@ date: '2026-01-06' sections: - security_fixes: - - | - Developers and administrators interacting with filter suggestions in the UI will see suggestion text rendered as plain text by default. Previously, display names could be shown as raw HTML, which risked displaying unintended formatting or unsafe content. bugs: - | On instances with GitHub Actions enabled, when administrators deleted a self-hosted runner from the service, the runner process continued running on the host and did not exit automatically. diff --git a/data/release-notes/enterprise-server/3-16/13.yml b/data/release-notes/enterprise-server/3-16/13.yml index 863581be325f..b4eb899a97b7 100644 --- a/data/release-notes/enterprise-server/3-16/13.yml +++ b/data/release-notes/enterprise-server/3-16/13.yml @@ -1,8 +1,5 @@ date: '2026-01-06' sections: - security_fixes: - - | - Developers and administrators interacting with filter suggestions in the UI will see suggestion text rendered as plain text by default. Previously, display names could be shown as raw HTML, which risked displaying unintended formatting or unsafe content. bugs: - | On instances with GitHub Actions enabled, when administrators deleted a self-hosted runner from the service, the runner process continued running on the host and did not exit automatically. diff --git a/data/release-notes/enterprise-server/3-17/10.yml b/data/release-notes/enterprise-server/3-17/10.yml index 9b6a9cfe0ba1..d3f719704284 100644 --- a/data/release-notes/enterprise-server/3-17/10.yml +++ b/data/release-notes/enterprise-server/3-17/10.yml @@ -1,8 +1,5 @@ date: '2026-01-06' sections: - security_fixes: - - | - Developers and administrators interacting with filter suggestions in the UI will see suggestion text rendered as plain text by default. Previously, display names could be shown as raw HTML, which risked displaying unintended formatting or unsafe content. bugs: - | On instances with GitHub Actions enabled, when administrators deleted a self-hosted runner from the service, the runner process continued running on the host and did not exit automatically. diff --git a/data/release-notes/enterprise-server/3-18/4.yml b/data/release-notes/enterprise-server/3-18/4.yml index 780ab7e6aab8..07b55637e1f6 100644 --- a/data/release-notes/enterprise-server/3-18/4.yml +++ b/data/release-notes/enterprise-server/3-18/4.yml @@ -1,8 +1,5 @@ date: '2026-01-06' sections: - security_fixes: - - | - Developers and administrators interacting with filter suggestions in the UI will see suggestion text rendered as plain text by default. Previously, display names could be shown as raw HTML, which risked displaying unintended formatting or unsafe content. bugs: - | On instances with GitHub Actions enabled, when administrators deleted a self-hosted runner from the service, the runner process continued running on the host and did not exit automatically. diff --git a/data/reusables/actions/attestation-virtual-registry.md b/data/reusables/actions/attestation-virtual-registry.md new file mode 100644 index 000000000000..3f11358cec43 --- /dev/null +++ b/data/reusables/actions/attestation-virtual-registry.md @@ -0,0 +1,4 @@ +The [attest](https://github.com/actions/attest) and [attest-build-provenance](https://github.com/actions/attest-build-provenance) actions automatically create storage records on the {% data variables.product.virtual_registry %} if both: + +* The `push-to-registry` option is set to `true` +* The workflow that includes the action has the `artifact-metadata: write` permission diff --git a/data/reusables/copilot/custom-instructions-note.md b/data/reusables/copilot/custom-instructions-note.md new file mode 100644 index 000000000000..b4d8c57e0ca9 --- /dev/null +++ b/data/reusables/copilot/custom-instructions-note.md @@ -0,0 +1,11 @@ +{% note %} + +Did you successfully add a custom instructions file to your repository? + +Yes No + +{% endnote %} + +## Repository custom instructions in use + +The instructions in the file(s) are available for use by {% data variables.product.prodname_copilot_short %} as soon as you save the file(s). The complete set of instructions will be automatically added to requests that you submit to {% data variables.product.prodname_copilot_short %} in the context of that repository. For example, they are added to the prompt you submit to {% data variables.copilot.copilot_chat_short %}. diff --git a/data/reusables/enterprise-migration-tool/deploy-key-bypass.md b/data/reusables/enterprise-migration-tool/deploy-key-bypass.md deleted file mode 100644 index 8786c6c8c50f..000000000000 --- a/data/reusables/enterprise-migration-tool/deploy-key-bypass.md +++ /dev/null @@ -1,4 +0,0 @@ -> [!NOTE] If the repository you are migrating has rulesets that the incoming repository doesn't match, the migration will be blocked. To bypass these rulesets and allow the migration, you can apply a ruleset bypass for all deploy keys in the target organization. -> -> Repository rulesets can be set at the organization level. If the incoming repository does not match any of these rulesets, you will need to use the deploy key bypass for each one. See [AUTOTITLE](/organizations/managing-organization-settings/creating-rulesets-for-repositories-in-your-organization#granting-bypass-permissions-for-your-branch-or-tag-ruleset). -> diff --git a/data/reusables/organizations/data_saved_for_reinstating_a_former_org_member.md b/data/reusables/organizations/data_saved_for_reinstating_a_former_org_member.md deleted file mode 100644 index 090bffd7957b..000000000000 --- a/data/reusables/organizations/data_saved_for_reinstating_a_former_org_member.md +++ /dev/null @@ -1,2 +0,0 @@ -> [!NOTE] -> When you remove a user from your organization, their membership data is saved for three months. You can restore their data, or any private forks they owned of your organization's repositories, if you invite the user to rejoin the organization within that time frame. For more information, see [AUTOTITLE](/organizations/managing-membership-in-your-organization/reinstating-a-former-member-of-your-organization). diff --git a/data/reusables/security/production-context-mdc-preview.md b/data/reusables/security/production-context-mdc-preview.md index 83b2160f776d..f75d4892f11f 100644 --- a/data/reusables/security/production-context-mdc-preview.md +++ b/data/reusables/security/production-context-mdc-preview.md @@ -1,2 +1,2 @@ > [!NOTE] -> Production context and the integration with {% data variables.product.prodname_microsoft_defender %} is in {% data variables.release-phases.public_preview %} and subject to change. +> The integration with {% data variables.product.prodname_microsoft_defender %} is in {% data variables.release-phases.public_preview %} and subject to change. diff --git a/data/variables/product.yml b/data/variables/product.yml index e312ead6376f..d8559892ceed 100644 --- a/data/variables/product.yml +++ b/data/variables/product.yml @@ -173,6 +173,7 @@ prodname_container_registries: 'Container registries' prodname_docker_registry_namespace: '{% ifversion fpt or ghec %}`docker.pkg.github.com`{% elsif ghes %}docker.HOSTNAME{% endif %}' prodname_container_registry_namespace: '{% ifversion fpt or ghec %}`ghcr.io`{% elsif ghes %}containers.HOSTNAME{% endif %}' prodname_npm_registry: 'npm registry' +virtual_registry: 'linked artifacts page' # GitHub Insights prodname_insights: 'GitHub Insights' diff --git a/src/audit-logs/data/fpt/organization.json b/src/audit-logs/data/fpt/organization.json index 647a55d5d9bf..0494c45b2b03 100644 --- a/src/audit-logs/data/fpt/organization.json +++ b/src/audit-logs/data/fpt/organization.json @@ -14145,6 +14145,34 @@ "programmatic_access_type" ] }, + { + "action": "repository_secret_scanning_extended_metadata.disabled", + "description": "Metadata for secret scanning alerts has been disabled at the repository level", + "docs_reference_links": "/code-security/secret-scanning/enabling-secret-scanning-features/enabling-extended-metadata-checks-for-your-repository", + "fields": [ + "actor", + "actor_id", + "user_agent", + "request_id", + "request_access_security_header", + "user", + "user_id", + "repo", + "repo_id", + "public_repo", + "org", + "org_id", + "action", + "_document_id", + "@timestamp", + "created_at", + "operation_type", + "business", + "business_id", + "actor_is_bot" + ], + "docs_reference_titles": "Enabling extended metadata checks for your repository" + }, { "action": "repository_secret_scanning_generic_secrets.disabled", "description": "Generic secrets have been disabled at the repository level", diff --git a/src/audit-logs/data/ghec/enterprise.json b/src/audit-logs/data/ghec/enterprise.json index 63eb619de483..45d00d451607 100644 --- a/src/audit-logs/data/ghec/enterprise.json +++ b/src/audit-logs/data/ghec/enterprise.json @@ -1875,6 +1875,29 @@ "user_id" ] }, + { + "action": "business.organizations_limit_warning", + "description": "An enterprise is approaching its organizations limit.", + "docs_reference_links": "N/A", + "fields": [ + "actor", + "actor_id", + "user_agent", + "request_id", + "request_access_security_header", + "name", + "limit", + "count", + "business", + "business_id", + "action", + "_document_id", + "@timestamp", + "created_at", + "operation_type", + "actor_is_bot" + ] + }, { "action": "business.proxy_security_header_disabled", "description": "The proxy security header was disabled for an enterprise. All users on the network can now access GitHub, unless blocked by other means.", @@ -17545,6 +17568,34 @@ "programmatic_access_type" ] }, + { + "action": "repository_secret_scanning_extended_metadata.disabled", + "description": "Metadata for secret scanning alerts has been disabled at the repository level", + "docs_reference_links": "/code-security/secret-scanning/enabling-secret-scanning-features/enabling-extended-metadata-checks-for-your-repository", + "fields": [ + "actor", + "actor_id", + "user_agent", + "request_id", + "request_access_security_header", + "user", + "user_id", + "repo", + "repo_id", + "public_repo", + "org", + "org_id", + "action", + "_document_id", + "@timestamp", + "created_at", + "operation_type", + "business", + "business_id", + "actor_is_bot" + ], + "docs_reference_titles": "Enabling extended metadata checks for your repository" + }, { "action": "repository_secret_scanning_generic_secrets.disabled", "description": "Generic secrets have been disabled at the repository level", @@ -19831,6 +19882,42 @@ ], "docs_reference_titles": "Managing your organization's SSH certificate authorities, Enforcing policies for security settings in your enterprise" }, + { + "action": "sso_lockdown.disable", + "description": "SSO lockdown for users was disabled.", + "docs_reference_links": "N/A", + "fields": [ + "user_agent", + "request_id", + "actor", + "actor_id", + "business", + "business_id", + "action", + "_document_id", + "@timestamp", + "created_at", + "operation_type" + ] + }, + { + "action": "sso_lockdown.enable", + "description": "SSO lockdown for users was enabled.", + "docs_reference_links": "N/A", + "fields": [ + "user_agent", + "request_id", + "actor", + "actor_id", + "business", + "business_id", + "action", + "_document_id", + "@timestamp", + "created_at", + "operation_type" + ] + }, { "action": "sso_redirect.disable", "description": "Automatic redirects for users to single sign-on (SSO) was disabled.", diff --git a/src/audit-logs/data/ghec/organization.json b/src/audit-logs/data/ghec/organization.json index 647a55d5d9bf..0494c45b2b03 100644 --- a/src/audit-logs/data/ghec/organization.json +++ b/src/audit-logs/data/ghec/organization.json @@ -14145,6 +14145,34 @@ "programmatic_access_type" ] }, + { + "action": "repository_secret_scanning_extended_metadata.disabled", + "description": "Metadata for secret scanning alerts has been disabled at the repository level", + "docs_reference_links": "/code-security/secret-scanning/enabling-secret-scanning-features/enabling-extended-metadata-checks-for-your-repository", + "fields": [ + "actor", + "actor_id", + "user_agent", + "request_id", + "request_access_security_header", + "user", + "user_id", + "repo", + "repo_id", + "public_repo", + "org", + "org_id", + "action", + "_document_id", + "@timestamp", + "created_at", + "operation_type", + "business", + "business_id", + "actor_is_bot" + ], + "docs_reference_titles": "Enabling extended metadata checks for your repository" + }, { "action": "repository_secret_scanning_generic_secrets.disabled", "description": "Generic secrets have been disabled at the repository level", diff --git a/src/audit-logs/lib/config.json b/src/audit-logs/lib/config.json index 61b2bed173cb..6c35c7b542b2 100644 --- a/src/audit-logs/lib/config.json +++ b/src/audit-logs/lib/config.json @@ -9,5 +9,5 @@ "git": "Note: Git events have special access requirements and retention policies that differ from other audit log events. For GitHub Enterprise Cloud, access Git events via the REST API only with 7-day retention. For GitHub Enterprise Server, Git events must be enabled in audit log configuration and are not included in search results.", "sso_redirect": "Note: Automatically redirecting users to sign in is currently in beta for Enterprise Managed Users and subject to change." }, - "sha": "b56a045f081573d27a98c40b4de1e4984095fe92" + "sha": "cae0414d457f280b90b251fbf911f44a709d6ca9" } \ No newline at end of file