Merge pull request github#27653 from github/ske-dep-api

[2022-06-16] Dependency submission API - new article + new subcategory

Author: saritai

content/code-security/guides.md

@@ -84,6 +84,7 @@ includeGuides:
   - /code-security/supply-chain-security/managing-vulnerabilities-in-your-projects-dependencies/viewing-and-updating-vulnerable-dependencies-in-your-repository
   - /code-security/supply-chain-security/understanding-your-software-supply-chain/about-dependency-review
   - /code-security/supply-chain-security/understanding-your-software-supply-chain/about-the-dependency-graph
+  - /code-security/supply-chain-security/understanding-your-software-supply-chain/using-the-dependency-submission-api
   - /code-security/supply-chain-security/understanding-your-software-supply-chain/exploring-the-dependencies-of-a-repository
 ---
 

content/code-security/supply-chain-security/understanding-your-software-supply-chain/exploring-the-dependencies-of-a-repository.md

@@ -42,6 +42,10 @@ Enterprise owners can configure the dependency graph at an enterprise level. For
 {% ifversion fpt or ghec %}
 Dependencies are grouped by ecosystem. You can expand a dependency to view its dependencies.  Dependencies on private repositories, private packages, or unrecognized files are shown in plain text. If the package manager for the dependency is in a public repository, {% data variables.product.product_name %} will display a link to that repository.
 
+{% ifversion dependency-submission-api %}
+Dependencies submitted to a project using the Dependency submission API (beta), although also grouped by ecosystem, are shown separately from dependencies identified through manifest or lock files in the repository. These submitted dependencies appear in the dependency graph as "Snapshot dependencies" because they are submitted as a snapshot, or set, of dependencies. For more information on using the dependency submission API, see "[Using the Dependency submission API](/code-security/supply-chain-security/understanding-your-software-supply-chain/using-the-dependency-submission-api)."
+{% endif %}
+
 If vulnerabilities have been detected in the repository, these are shown at the top of the view for users with access to {% data variables.product.prodname_dependabot_alerts %}.
 
 ![Dependencies graph](/assets/images/help/graphs/dependencies_graph.png)

content/code-security/supply-chain-security/understanding-your-software-supply-chain/index.md

@@ -14,6 +14,7 @@ children:
   - /about-supply-chain-security
   - /about-the-dependency-graph
   - /configuring-the-dependency-graph
+  - /using-the-dependency-submission-api
   - /about-dependency-review
   - /configuring-dependency-review
   - /exploring-the-dependencies-of-a-repository

content/code-security/supply-chain-security/understanding-your-software-supply-chain/using-the-dependency-submission-api.md

@@ -0,0 +1,86 @@
+---
+title: Using the Dependency submission API
+intro: 'You can use the Dependency submission API to submit dependencies for projects, such as the dependencies resolved when a project is built or compiled.'
+shortTitle: Dependency submission API
+topics:
+  - API
+  - Dependency graph
+  - Dependencies
+  - REST
+versions:
+  feature: dependency-submission-api
+---
+
+{% data reusables.dependency-submission.dependency-submission-api-beta %}
+
+## About the Dependency submission API
+
+{% data reusables.dependency-submission.about-dependency-submission %}
+
+Dependencies are submitted to the dependency submission API in the form of a snapshot. A snapshot is a set of dependencies associated with a commit SHA and other metadata, that reflects the current state of your repository for a commit. For more information about the Dependency submission API, see the [Dependency submission REST API documentation](/rest/dependency-graph/dependency-submission).
+
+## Submitting dependencies at build-time
+
+You can use the Dependency submission API in a {% data variables.product.prodname_actions %} workflow to submit dependencies for your project when your project is built. 
+
+### Using pre-made actions
+
+The simplest way to use the Dependency submission API is by adding a pre-made action to your repository that will gather and convert the list of dependencies to the required snapshot format and submit the list to the API. Actions that complete these steps for various ecosystems are available on {% data variables.product.prodname_marketplace %} and more actions will be created during the course of the beta and beyond. You can find links to the currently available actions in the table below:
+
+Ecosystem | Action |
+--- | --- |
+Go | [Go Dependency Submission](https://github.com/actions/go-dependency-submission)
+
+For example, the following [Go Dependency Submission](https://github.com/actions/go-dependency-submission) workflow calculates the dependencies for a Go build-target (a Go file with a `main` function) and submits the list to the Dependency Submission API. 
+
+```yaml
+
+name: Go Dependency Submission
+on:
+  push:
+    branches:
+      - main
+      
+# The API requires write permission on the repository to submit dependencies
+permissions:
+  contents: write
+
+# Envionment variables to configure Go and Go modules. Customize as necessary
+env:
+  GOPROXY: '' # A Go Proxy server to be used
+  GOPRIVATE: '' # A list of modules are considered private and not requested from GOPROXY
+jobs:
+  go-action-detection:
+    runs-on: ubuntu-latest
+    steps:
+      - name: 'Checkout Repository'
+        uses: {% data reusables.actions.action-checkout %}
+        
+      - uses: {% data reusables.actions.action-setup-go %}
+        with:
+          go-version: ">=1.18.0"
+          
+      - name: Run snapshot action
+        uses: @actions/go-dependency-submission@v1
+        with:
+            # Required: Define the repo path to the go.mod file used by the
+            # build target
+            go-mod-path: go-example/go.mod
+            #
+            # Optional. Define the repo path of a build target,
+            # a file with a `main()` function.
+            # If undefined, this action will collect all dependencies
+            # used by all build targets for the module. This may
+            # include Go dependencies used by tests and tooling.
+            go-build-target: go-example/cmd/octocat.go
+
+```
+### Creating your own action
+
+Alternatively, you can write your own action to submit dependencies for your project at build-time. Your workflow should:
+
+  1. Generate a list of dependencies for your project.
+  2. Translate the list of dependencies into the snapshot format accepted by the Dependency submission API. For more information about the format, see the body parameters for the "Create a repository snapshot" API operation in the [Dependency submission REST API documentation](/rest/dependency-graph/dependency-submission).
+  3. Submit the formatted list of dependencies to the Dependency submission API.
+
+{% data variables.product.product_name %} maintains the [Dependency Submission Toolkit](https://github.com/github/dependency-submission-toolkit), a TypeScript library to help you build your own GitHub Action for submitting dependencies to the Dependency submission API. For more information about writing an action, see "[Creating actions](/actions/creating-actions)".

content/rest/dependency-graph/dependency-submission.md

@@ -0,0 +1,17 @@
+---
+title: Dependency submission
+intro: 'The Dependency submission API allows you to submit dependencies for projects, such as the dependencies resolved when a project is built or compiled.'
+versions:
+  feature: dependency-submission-api
+miniTocMaxHeadingLevel: 3
+---
+
+## About the Dependency submission API
+
+{% data reusables.dependency-submission.dependency-submission-api-beta %}
+
+{% data reusables.dependency-submission.about-dependency-submission %}
+
+Dependencies are submitted to the dependency submission API in the form of a snapshot. A snapshot is a set of dependencies associated with a commit SHA and other metadata, that reflects the current state of your repository for a commit.  You can choose to use pre-made actions or create your own actions to submit your dependencies to the dependency submission API in the required format each time your project is built. For more information about using the Dependency submission API, see "[Using the Dependency submission API](/code-security/supply-chain-security/understanding-your-software-supply-chain/using-the-dependency-submission-api)."
+
+You can submit multiple sets of dependencies to the Dependency submission API to be included in your dependency graph. The API uses the `job.correlator` property and the `detector.name` category of the snapshot to ensure the latest submissions for each workflow get shown. The `correlator` property itself is the primary field you will use to keep independent submissions distinct. An example `correlator` could be a simple combination of two variables available in actions runs: `<GITHUB_WORKFLOW> <GITHUB_JOB>`.

content/rest/dependency-graph/index.md

@@ -11,6 +11,7 @@ topics:
 miniTocMaxHeadingLevel: 3
 children:
   - /dependency-review
+  - /dependency-submission
 redirect_from:
   - /rest/reference/dependency-graph
 ---

data/features/dependency-submission-api.yml

@@ -0,0 +1,6 @@
+# Issue 6397
+versions:
+  fpt: '*'
+  ghec: '*'
+  ghes: '>3.6'
+  ghae: 'issue-6397'

data/reusables/dependency-submission/about-dependency-submission.md

@@ -0,0 +1,5 @@
+The Dependency submission API lets you submit dependencies for a project. This enables you to add dependencies, such as those resolved when software is compiled or built, to {% data variables.product.prodname_dotcom %}'s dependency graph feature, providing a more complete picture of all of your project's dependencies.
+
+The dependency graph shows any dependencies you submit using the API in addition to any dependencies that are identified from manifest or lock files in the repository (for example, a `package-lock.json` file in a JavaScript project). For more information about viewing the dependency graph, see "[Exploring the dependencies of a repository](/code-security/supply-chain-security/understanding-your-software-supply-chain/exploring-the-dependencies-of-a-repository#viewing-the-dependency-graph)." 
+
+Submitted dependencies will receive {% data variables.product.prodname_dependabot_alerts %}, {% data variables.product.prodname_dependabot_version_updates %} and {% data variables.product.prodname_dependabot_security_updates %} for any known vulnerabilities. You will only get {% data variables.product.prodname_dependabot_alerts %} for dependencies that are from one of the [supported ecosystems](https://github.com/github/advisory-database#supported-ecosystems) of the {% data variables.product.prodname_advisory_database %}. Submitted dependencies will not be surfaced in dependency review or your organization's dependency insights.

data/reusables/dependency-submission/dependency-submission-api-beta.md

@@ -0,0 +1,5 @@
+{% note %}
+
+**Note:** The Dependency submission API is currently in public beta and subject to change.
+
+{% endnote %}

lib/redirects/static/client-side-rest-api-redirects.json

@@ -569,6 +569,8 @@
   "/rest/dependabot#delete-a-repository-secret": "/rest/dependabot/secrets#delete-a-repository-secret",
   "/rest/dependency-graph#get-a-diff-of-the-dependencies-between-commits": "/rest/dependency-graph/dependency-review#get-a-diff-of-the-dependencies-between-commits",
   "/rest/dependency-graph#dependency-review": "/rest/dependency-graph/dependency-review",
+  "/rest/dependency-graph#create-a-snapshot-of-dependencies-for-a-repository": "/rest/dependency-graph/dependency-submission#create-a-snapshot-of-dependencies-for-a-repository",
+  "/rest/dependency-graph#dependency-submission": "/rest/dependency-graph/dependency-submission",
   "/rest/deployments#deployments": "/rest/deployments/deployments",
   "/rest/deployments#statuses": "/rest/deployments/statuses",
   "/rest/repos#create-a-repository-dispatch-event": "/rest/repos/repos#create-a-repository-dispatch-event",