Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

📖 Move authentication section in README.md to the beginning of the Usage section. #888

Merged
merged 2 commits into from
Aug 24, 2021
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
73 changes: 37 additions & 36 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,11 +11,11 @@
* [Goals](#goals)
* [Scorecard Checks](#scorecard-checks)
* [Usage](#usage)
* [Authentication](#authentication)
* [Docker](#docker)
* [Using repository URL](#using-repository-url)
* [Using a Package manager](#using-a-package-manager)
* [Running specific checks](#running-specific-checks)
* [Authentication](#authentication)
* [Understanding Scorecard results](#understanding-scorecard-results)
* [Formatting Results](#formatting-results)
* [Public Data](#public-data)
Expand Down Expand Up @@ -67,6 +67,42 @@ the [checks documentation page](docs/checks.md).

## Usage

### Authentication

Before running Scorecard, you need to, either:

- [create a GitHub access token](https://docs.github.com/en/free-pro-team@latest/developers/apps/about-apps#personal-access-tokens)
and set it in an environment variable called `GITHUB_AUTH_TOKEN`,
`GITHUB_TOKEN`, `GH_AUTH_TOKEN` or `GH_TOKEN`. This helps to avoid the
GitHub's [api rate limits](https://developer.github.com/v3/#rate-limiting)
with unauthenticated requests.

```shell
# For posix platforms, e.g. linux, mac:
export GITHUB_AUTH_TOKEN=<your access token>
# Multiple tokens can be provided separated by comma to be utilized
# in a round robin fashion.
export GITHUB_AUTH_TOKEN=<your access token1>,<your access token2>

# For windows:
set GITHUB_AUTH_TOKEN=<your access token>
set GITHUB_AUTH_TOKEN=<your access token1>,<your access token2>
```

- create a GitHub App Installations for higher rate-limit quotas. If you have
an installed GitHub App and key file, you can use these three environment
variables, following the commands shown above for your platform.

```
GITHUB_APP_KEY_PATH=<path to the key file on disk>
GITHUB_APP_INSTALLATION_ID=<installation id>
GITHUB_APP_ID=<app id>
```

These can be obtained from the GitHub
[developer settings](https://github.com/settings/apps) page.


### Docker

`scorecard` is available as a Docker container:
Expand Down Expand Up @@ -220,41 +256,6 @@ names.

For example, `--checks=CI-Tests,Code-Review`.

### Authentication

Before running Scorecard, you need to, either:

- [create a GitHub access token](https://docs.github.com/en/free-pro-team@latest/developers/apps/about-apps#personal-access-tokens)
and set it in an environment variable called `GITHUB_AUTH_TOKEN`,
`GITHUB_TOKEN`, `GH_AUTH_TOKEN` or `GH_TOKEN`. This helps to avoid the
GitHub's [api rate limits](https://developer.github.com/v3/#rate-limiting)
with unauthenticated requests.

```shell
# For posix platforms, e.g. linux, mac:
export GITHUB_AUTH_TOKEN=<your access token>
# Multiple tokens can be provided separated by comma to be utilized
# in a round robin fashion.
export GITHUB_AUTH_TOKEN=<your access token1>,<your access token2>

# For windows:
set GITHUB_AUTH_TOKEN=<your access token>
set GITHUB_AUTH_TOKEN=<your access token1>,<your access token2>
```

- create a GitHub App Installations for higher rate-limit quotas. If you have
an installed GitHub App and key file, you can use these three environment
variables, following the commands shown above for your platform.

```
GITHUB_APP_KEY_PATH=<path to the key file on disk>
GITHUB_APP_INSTALLATION_ID=<installation id>
GITHUB_APP_ID=<app id>
```

These can be obtained from the GitHub
[developer settings](https://github.com/settings/apps) page.

### Understanding Scorecard results

Each check returns a **Pass / Fail** decision, as well as a confidence score
Expand Down