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.

Sign up for GitHub

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

Jump to bottom

Document all environment variables used #187

Open
wants to merge 2 commits into
base: master
Choose a base branch
from
Open

Document all environment variables used #187

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
3f33de4
Document all environment variables used
gdm85 Nov 3, 2020
9ac8430
Remove duplicate environment parsing for BUILDKITE_PULL_REQUEST
gdm85 Nov 3, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
35 changes: 26 additions & 9 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,31 +12,48 @@ continuous code coverage tracking system.
$ go get github.com/mattn/goveralls
```


# Usage

First you will need an API token. It is found at the bottom of your
repository's page when you are logged in to Coveralls.io. Each repo has its
own token.
For non-public repositories you will need a Coveralls.io token; it is found at the bottom of your
repository's page when you are logged in to Coveralls.io. Each repository has its own token.

```bash
$ cd $GOPATH/src/github.com/yourusername/yourpackage
$ goveralls -repotoken your_repos_coveralls_token
```

You can set the environment variable `$COVERALLS_TOKEN` to your token so you do
not have to specify it at each invocation.

It is advised to set the environment variable `COVERALLS_TOKEN` to your token so you do
not have to specify it at each invocation through `-repotoken`, which is less secure.

You can also run this reporter for multiple passes with the flag `-parallel` or
by setting the environment variable `COVERALLS_PARALLEL=true` (see [coveralls
docs](https://docs.coveralls.io/parallel-build-webhook) for more details).

`goveralls` will run the entire test suite when no coverage profile files are provided with `-coverprofile`;
you can use `-flags` to pass extra flags to the Go tests run by goveralls.

## Environment variables

Some metadata used when submitting a Coveralls.io job can be specified via any of the mentioned environment variables:

* job ID: `COVERALLS_SERVICE_JOB_ID`, `TRAVIS_JOB_ID`, `CIRCLE_BUILD_NUM`, `APPVEYOR_JOB_ID`, `SEMAPHORE_BUILD_NUMBER`, `BUILD_NUMBER`, `BUILDKITE_BUILD_ID`, `DRONE_BUILD_NUMBER`, `BUILDKITE_BUILD_NUMBER`, `CI_BUILD_ID`, `GITHUB_RUN_ID`
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I believe it's extraneous to specify all environment variables that are maintained as part of CI integrations. Most just exist without the user needing to do something about them.

It should be sufficient to either have a couple of them standardized like git info/branch name, if we don't add them as command line options.

Though by design of the cli, seems adding them as options is more consistent.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Disagree; you might be using Docker in one of these integrations (Jenkins for example) and then you need to know which environment variables are used by goveralls.

See for example how it is done for coveralls-python: https://github.com/coveralls-clients/coveralls-python/blob/6c8639cc22a5d9ef9f7e46fdb008fb3f53b99f26/docs/usage/tox.rst

Though by design of the cli, seems adding them as options is more consistent.

I don't see the current environment variables being replaced with CLI options any time soon, so documenting them is the minimum we can do. Some of them have tricky side-effects (see the GitHub Action integration or the Travis-CI case) which are also currently undocumented.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Alternatively, I could suggest documenting only a few "standard" environment variables, if the only objective is to pass them through to goveralls within a docker build.

BUILD_NUMBER, BRANCH_NAME and PULL_REQUEST_NUMBER can be documented to pass the individual CI env parameters to goveralls. The individual CI-specific environment variables differ drastically and, if required, may be documented in the CI's own section.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The individual CI-specific environment variables differ drastically and, if required, may be documented in the CI's own section.

I would rather go this way.

I could suggest documenting only a few "standard" environment variables, if the only objective is to pass them through to goveralls within a docker build.

When one is using Docker in Jenkins then the environment variables of Jenkins should be used; same goes for any other exotic combination which is in place, so I prefer to document them all for each C.I.

I will adjust this PR accordingly.

* branch name: `GIT_BRANCH`, `GITHUB_HEAD_REF`, `GITHUB_REF`, `CIRCLE_BRANCH`, `TRAVIS_BRANCH`, `CI_BRANCH`, `APPVEYOR_REPO_BRANCH`, `WERCKER_GIT_BRANCH`, `DRONE_BRANCH`, `BUILDKITE_BRANCH`, `BRANCH_NAME`
* pull request number: `CIRCLE_PR_NUMBER`, `TRAVIS_PULL_REQUEST`, `APPVEYOR_PULL_REQUEST_NUMBER`, `PULL_REQUEST_NUMBER`, `BUILDKITE_PULL_REQUEST`, `DRONE_PULL_REQUEST`, `CI_PR_NUMBER`
* pull request number (extracted with regex): `CI_PULL_REQUEST`, `GITHUB_EVENT_NAME`
* repository token: `COVERALLS_TOKEN`
* repository token file: `COVERALLS_TOKEN_FILE`
* parallel flag: `COVERALLS_PARALLEL`
* Coveralls.io job flag name: `COVERALLS_FLAG_NAME`
* repository name: `GITHUB_REPOSITORY`

### Special cases

* when `TRAVIS_JOB_ID` is specified then `-service` will automatically be set to `travis-ci`.
* when `GITHUB_EVENT_NAME` is set to `pull_request` then the file at `GITHUB_EVENT_PATH` will be attempted read and used to parse the pull request number and the Git HEAD reference.

# Continuous Integration

There is no need to run `go test` separately, as `goveralls` runs the entire
test suite.
It is possible to use goveralls with any Continuous Integration platform; integration with the most common ones is explained below with some examples.

## Github Actions

Expand Down
2 changes: 0 additions & 2 deletions goveralls.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -386,8 +386,6 @@ func process() error {
pullRequest = prNumber
} else if prNumber := os.Getenv("PULL_REQUEST_NUMBER"); prNumber != "" {
pullRequest = prNumber
} else if prNumber := os.Getenv("BUILDKITE_PULL_REQUEST"); prNumber != "" {
pullRequest = prNumber
} else if prNumber := os.Getenv("DRONE_PULL_REQUEST"); prNumber != "" {
pullRequest = prNumber
} else if prNumber := os.Getenv("BUILDKITE_PULL_REQUEST"); prNumber != "" {
Expand Down