📖 Update installation instructions to match current GitHub UI (#1153)

* feat: update install instructions Signed-off-by: Joyce Brum <[email protected]> * Add new screenshots Signed-off-by: Joyce <[email protected]> * Add files via upload Signed-off-by: Joyce <[email protected]> * feat: rename screenshots Signed-off-by: Joyce Brum <[email protected]> * feat: update README Signed-off-by: Joyce Brum <[email protected]> --------- Signed-off-by: Joyce Brum <[email protected]> Signed-off-by: Joyce <[email protected]>
ossf · Jun 2, 2023 · 19b683b · 19b683b
1 parent ab67918
commit 19b683b
Show file tree

Hide file tree

Showing 7 changed files with 29 additions and 33 deletions.
diff --git a/README.md b/README.md
@@ -12,19 +12,19 @@ Starting from scorecard-action:v2, `GITHUB_TOKEN` permissions or job permissions
 `id-token: write` for `publish_results: true`. This is needed to access GitHub's
 OIDC token which verifies the authenticity of the result when publishing it.
 
-scorecard-action:v2 has a new requirement for the job running the ossf/scorecard-action step. The steps running in this job must belong to this approved list of GitHub actions: 
-- "actions/checkout" 
+scorecard-action:v2 has a new requirement for the job running the ossf/scorecard-action step. The steps running in this job must belong to this approved list of GitHub actions:
+- "actions/checkout"
 - "actions/upload-artifact"
 - "github/codeql-action/upload-sarif"
 - "ossf/scorecard-action"
 
 If you are using custom steps in the job, it may fail.
-We understand that this is restrictive, but currently it's necessary to ensure the integrity of the results that we publish, since GitHub workflow steps run in the same environment as the job they belong to. 
-If possible, we will work on making this feature more flexible so we can drop this requirement in the future.  
+We understand that this is restrictive, but currently it's necessary to ensure the integrity of the results that we publish, since GitHub workflow steps run in the same environment as the job they belong to.
+If possible, we will work on making this feature more flexible so we can drop this requirement in the future.
 ________
 [Personal Access Token (PAT) Requirements and Risks](#personal-access-token-pat-requirements-and-risks)
 
-[Installation](#installation) 
+[Installation](#installation)
 - [Workflow Setup](#workflow-setup-required)
 - [Authentication](#authentication-with-pat-optional)
 
@@ -52,7 +52,7 @@ GitHub Enterprise repositories are not supported.
 
 ## Personal Access Token (PAT) Requirements and Risks
 
-Certain features require a Personal Access Token (PAT). 
+Certain features require a Personal Access Token (PAT).
 
 -  Public repositories need a PAT to enable the
     [Branch-Protection](https://github.com/ossf/scorecard/blob/main/docs/checks.md#branch-protection)
@@ -69,50 +69,46 @@ and be accessible by all the workflows and maintainers of a repository.**
 This means another maintainer on your project could potentially use the token to impersonate you. If there is an exploitable bug in a workflow with write permissions, an external contributor could potentially exploit it to extract the PAT.
 
 We recommend that you **do not use a PAT** unless you feel that the
-risks introduced are outweighed by the functionalities they support. 
+risks introduced are outweighed by the functionalities they support.
 
 ## Installation
 
 ### Workflow Setup (Required)
-1) From your GitHub project's main page, click “Security” in the top ribbon. 
+1) From your GitHub project's main page, click “Security” in the top ribbon.
 
 ![image](/images/install01.png)
 
-2) Click “Set up Code Scanning.” 
+2) Select “Code scanning”.
 
 ![image](/images/install02.png)
 
-Note: if you have already configured other code scanning tools, your UI will look different than shown above. Instead, click "Code Scanning Alerts" on the left side of the page. 
-
-![image](/images/installb1.png)
-
-Then click "Add More Scanning Tools."
-
-![image](/images/installb2.png)
-
-3) Choose the "OSSF Scorecards supply-chain security analysis" from the list of workflows, and then click “set up this workflow.”
+3) Then click "Add tool".
 
 ![image](/images/install03.png)
 
-4) Commit the changes.
+4) Choose the "OSSF Scorecard" from the list of workflows, and then click “Configure”.
 
 ![image](/images/install04.png)
 
+5) Commit the changes.
+
+![image](/images/install05.png)
+
 ### Authentication with PAT (optional)
-Create a Personal Access Token (PAT) for authentication and save the token value as a repository secret. Review [Personal Access Token (PAT) Requirements and Risks](#personal-access-token-pat-requirements-and-risks) before using a PAT.  
+Create a Personal Access Token (PAT) for authentication and save the token value as a repository secret. Review [Personal Access Token (PAT) Requirements and Risks](#personal-access-token-pat-requirements-and-risks) before using a PAT.
 
 1. [Create a Personal Access Token](https://github.com/settings/tokens/new?scopes=public_repo,read:org,read:repo_hook,read:discussion) with the following read permissions:
     - Note: `Token for OSSF Scorecard Action - myorg/myrepo` (Note: replace `myorg/myrepo` with the names of your organization and repository so you can keep track of your tokens.)
     - Expiration: `No expiration`
-    - Scopes: 
+    - Scopes:
         * `repo > public_repo`                  Required to read [Branch-Protection](https://github.com/ossf/scorecard/blob/main/docs/checks.md#branch-protection) settings. **Note**: for private repositories, you need scope `repo`.
         * `admin:org > read:org`                Optional: not used in current implementation.
         * `admin:repo_hook > read:repo_hook`    Optional: needed for the experimental [Webhook](https://github.com/ossf/scorecard/blob/main/docs/checks.md#webhooks) check.
         * `write:discussion > read:discussion`  Optional: not used in current implementation.
 
 ![image](/images/tokenscopes.png)
 
-2. Copy the token value. 
+2. Copy the token value.
 
 3. [Create a new repository secret](https://docs.github.com/en/actions/security-guides/encrypted-secrets#creating-encrypted-secrets-for-a-repository) with the following settings (**Warning:** [GitHub encrypted secrets](https://docs.github.com/en/actions/security-guides/encrypted-secrets) are accessible by all the workflows and maintainers of a repository.):
     - Name: `SCORECARD_TOKEN`
@@ -125,7 +121,7 @@ Create a Personal Access Token (PAT) for authentication and save the token value
 The workflow is preconfigured to run on every repository contribution. After making a code change, you can view the results for the change either through the Scorecard Badge, Code Scanning Alerts or GitHub Workflow Runs.
 
 ### REST API
-Starting with scorecard-action:v2, users can use a REST API to query their latest run results. This requires setting [`publish_results: true`](https://github.com/ossf/scorecard/blob/d13ba3f3355b958d5d62edc47282a2e7ed9fa7c1/.github/workflows/scorecard-analysis.yml#L39) for the action and enabling [`id-token: write`](https://github.com/ossf/scorecard/blob/d13ba3f3355b958d5d62edc47282a2e7ed9fa7c1/.github/workflows/scorecard-analysis.yml#L22) permission for the job (needed to access GitHub OIDC token). The API is available here: https://api.securityscorecards.dev. 
+Starting with scorecard-action:v2, users can use a REST API to query their latest run results. This requires setting [`publish_results: true`](https://github.com/ossf/scorecard/blob/d13ba3f3355b958d5d62edc47282a2e7ed9fa7c1/.github/workflows/scorecard-analysis.yml#L39) for the action and enabling [`id-token: write`](https://github.com/ossf/scorecard/blob/d13ba3f3355b958d5d62edc47282a2e7ed9fa7c1/.github/workflows/scorecard-analysis.yml#L22) permission for the job (needed to access GitHub OIDC token). The API is available here: https://api.securityscorecards.dev.
 
 ### Scorecard Badge
 
@@ -145,26 +141,26 @@ A list of results is accessible by going in the Security tab and clicking "Code
 
 ![image](/images/remediation.png)
 
-### Verify Runs 
-The workflow is preconfigured to run on every repository contribution. 
+### Verify Runs
+The workflow is preconfigured to run on every repository contribution.
 
 To verify that the Action is running successfully, click the repository's Actions tab to see the status of all recent workflow runs. This tab will also show the logs, which can help you troubleshoot if the run failed.
 
 ![image](/images/actionconfirm.png)
 
-### Troubleshooting 
+### Troubleshooting
 If the run has failed, the most likely reason is an authentication failure. If you are running Scorecards on a private repository, confirm that the Personal Access Token is saved as an encrypted secret within the same repository (see [Authentication](#authentication)). In addition, provide the `repo` scope to your PAT. (The `repo > public_repo` scope only provides access to public repositories).
 
 If you install Scorecards on a repository owned by an organization that uses [SAML SSO](https://docs.github.com/en/enterprise-cloud@latest/authentication/authenticating-with-saml-single-sign-on/about-authentication-with-saml-single-sign-on) or if you see `403 Resource protected by organization SAML enforcement` in the logs, be sure to [enable SSO](https://docs.github.com/en/enterprise-cloud@latest/authentication/authenticating-with-saml-single-sign-on/authorizing-a-personal-access-token-for-use-with-saml-single-sign-on) for your PAT token (see [Authentication](#authentication)).
 
 If you use a PAT saved as an encrypted secret and the run is still failing, confirm that you have not made any changes to the workflow yaml file that affected the syntax. Review the [workflow example](#workflow-example) and reset to the default values if necessary.
 
 ## Manual Action Setup
-    
+
 If you prefer to manually set up the Scorecards GitHub Action, you will need to set up a [workflow file](https://docs.github.com/en/actions/learn-github-actions/workflow-syntax-for-github-actions).
 
 First, [create a new file](https://docs.github.com/en/repositories/working-with-files/managing-files/creating-new-files) in this location: `[yourrepo]/.github/workflows/scorecards.yml`. Then use the input values below.
- 
+
 
 ### Inputs
 
@@ -176,17 +172,17 @@ First, [create a new file](https://docs.github.com/en/repositories/working-with-
 | `publish_results` | recommended | This will allow you to display a badge on your repository to show off your hard work (release scheduled for Q2'22). See details [here](#publishing-results).|
 
 ### Publishing Results
-The Scorecard team runs a weekly scan of public GitHub repositories in order to track 
+The Scorecard team runs a weekly scan of public GitHub repositories in order to track
 the overall security health of the open source ecosystem. The results of the scans are [publicly
 available](https://github.com/ossf/scorecard#public-data).
-Setting `publish_results: true` replaces the results of the team's weekly scans with your own scan results, 
+Setting `publish_results: true` replaces the results of the team's weekly scans with your own scan results,
 helping us scale by cutting down on repeated workflows and GitHub API requests.
-This option is also needed to enable badges on the repository (release scheduled for Q2'22). 
+This option is also needed to enable badges on the repository (release scheduled for Q2'22).
 
 ### Uploading Artifacts
-The Scorecards Action uses the [artifact uploader action](https://github.com/actions/upload-artifact) to upload results in SARIF format to the Actions tab. These results are available to anybody for five days after the run to help with debugging. To disable the upload, comment out the `Upload Artifact` value in the Workflow Example. 
+The Scorecards Action uses the [artifact uploader action](https://github.com/actions/upload-artifact) to upload results in SARIF format to the Actions tab. These results are available to anybody for five days after the run to help with debugging. To disable the upload, comment out the `Upload Artifact` value in the Workflow Example.
 
-Note: if you disable this option, the results of the Scorecards Action run will be available only to maintainers (on the Security tab scanning dashboard). 
+Note: if you disable this option, the results of the Scorecards Action run will be available only to maintainers (on the Security tab scanning dashboard).
 
 ### Workflow Example
 

diff --git a/images/install02.png b/images/install02.png
diff --git a/images/install03.png b/images/install03.png
diff --git a/images/install04.png b/images/install04.png
diff --git a/images/install05.png b/images/install05.png
diff --git a/images/installb1.png b/images/installb1.png
diff --git a/images/installb2.png b/images/installb2.png