Suggestion: Improvements in docs regarding generic CI env vars

[abravalheri]

Hello, this documentation page specifies a series of environment variables that, when defined during the build are enough to support integration with coveralls. The problem is that the page does not provide any hint on what is the meaning/expected values for each of those variables.

After spending some time reading the official Ruby client implementation and doing some cross-correlation with the env variables documentation in the supported CI services (e.g. Travis, Semaphore, Circle, Jenkins, GitLab, GitHub, etc), I suppose the following description makes some sense:

• CI_NAME: Name of the CI service being used
• CI_BUILD_NUMBER: Number (counter) relative to the current build
• CI_BUILD_URL: URL to a webpage showing the build information/output
• CI_BRANCH: For pull requests this is the name of the branch targeted by the PR, otherwise it corresponds to the name of the current branch or tag
• CI_JOB_ID (optional): Unique identifier of the job in the CI service. When missing, CI_BUILD_NUMBER is used
• CI_PULL_REQUEST (optional): If given, corresponds to the number of the pull request, as specified in the supported repository hosting service (GitHub, GitLab, etc)

My suggestion would be adding something similar to the text above to the docs.
Similarly, the API docs https://docs.coveralls.io/api-reference could be updated with similar descriptions for some of the missing (but accepted keys) for JOB objects (e.g. service_number, service_build_url, service_branch)

[afinetooth]

Thanks @abravalheri.

We're in progress on a major docs update. It is indeed our intent to clarify those env var values and how they map to the JSON params expected by the Coveralls API.

These are good assessments of the values expected for each of the env vars. Final definitions will be very similar to your recommendations.

We also hope to identify the relevant env vars for each supported CI service, similar to the mappings you found in coveralls-ruby.

I would modify two (2) of the above definitions slightly:

• CI_BUILD_NUMBER: The number assigned to the build by your CI service.
• CI_JOB_ID: For parallel builds, the number assigned to each job comprising the build. When missing, Coveralls will assign an incrementing integer (1, 2, 3...). This value should not change between multiple runs of the build.

[abravalheri]

Thank you very much @afinetooth for the reply. I have recently submitted a PR for the Python client that adds support for those environment variables (they were present in the official docs, but so far they seem to be ignored by the Python client), so I will update there the descriptions with your suggestions.

I will close the issue now, because my doubts were clarified, but please feel free to reopen it if you guys like to keep it as a reminder for docs update.