From 2382e415256b1e504410b0b4df3d0a0d051eea86 Mon Sep 17 00:00:00 2001 From: Edvin Norling Date: Fri, 3 Jul 2026 08:35:24 +0200 Subject: [PATCH] Config GitHub App instructions Relates to https://github.com/DependencyTrack/dependency-track/pull/6564 Signed-off-by: Edvin Norling --- .../configuring-vulnerability-sources.md | 28 ++++++++++++++++--- 1 file changed, 24 insertions(+), 4 deletions(-) diff --git a/docs/guides/administration/configuring-vulnerability-sources.md b/docs/guides/administration/configuring-vulnerability-sources.md index e99bf642..b38e5415 100644 --- a/docs/guides/administration/configuring-vulnerability-sources.md +++ b/docs/guides/administration/configuring-vulnerability-sources.md @@ -20,9 +20,17 @@ For each source you plan to enable, allow outbound HTTPS access from the API ser If outbound traffic must go through a proxy, see [Configuring an HTTP proxy](configuring-http-proxy.md). If the proxy intercepts TLS, see [Configuring internal CA trust](configuring-internal-ca.md). -The GitHub advisories source also requires a GitHub personal access token (PAT). The token needs no scopes, but the -GitHub GraphQL API rejects unauthenticated requests. Create one at -[github.com/settings/tokens](https://github.com/settings/tokens). NVD and OSV do not require credentials. +The GitHub advisories source rejects unauthenticated requests, so it needs GitHub credentials. Authenticate with either a +personal access token (PAT) or a GitHub App. NVD and OSV do not require credentials. + +- **Personal access token**: the simplest option. The token needs no scopes, because it is used only to authenticate. +Create one at [github.com/settings/tokens](https://github.com/settings/tokens). Both fine-grained and classic tokens work. +A PAT is tied to the user who created it. +- **GitHub App**: use this when you want credentials owned by an organization rather than a person. Dependency-Track mints and refreshes short-lived installation tokens automatically. +[Register an App](https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/registering-a-github-app) +on the organization, install it, and note the App ID, installation ID, and a generated private key. + +Choose one method. The two are mutually exclusive. ## Enabling sources @@ -49,11 +57,23 @@ works](../../concepts/about-vulnerability-data-sources.md#how-component-matching 1. Open **Administration > Vulnerability Sources > GitHub**. 2. Enable the source. -3. Enter the GitHub PAT from the prerequisites. +3. Enter the credentials from the prerequisites: + - For a **personal access token**, enter the token in **API Token**. + - For a **GitHub App**, enter the **App ID**, **Installation ID**, and **App Private Key**, and leave **API Token** + empty. 4. Select **Mirror now** to download advisories immediately. ![GitHub Advisories configuration](../../assets/images/guides/administration/configuring-vulnerability-sources/github.png) +!!! note "Convert the GitHub App private key to PKCS#8" + GitHub delivers App private keys in PKCS#1 format (the file starts with `-----BEGIN RSA PRIVATE KEY-----`), but + Dependency-Track requires PKCS#8 (`-----BEGIN PRIVATE KEY-----`). Convert the key once, then paste the converted + contents into **App Private Key**: + + ```bash + openssl pkcs8 -topk8 -nocrypt -in github-app.pem -out github-app.pk8.pem + ``` + ### OSV 1. Open **Administration > Vulnerability Sources > OSV**.