@@ -6,8 +6,8 @@ The following is a set of guidelines for contributing to this repository, which
## What does this repo do?
This repo is a GitHub Action, meaning it integrates with the GitHub Actions CI/CD pipeline. It's meant to take formatted reports with code coverage stats and upload them to codecov.io. What's essentially happening in the background is that Actions is spinning up a Linux Docker container with the contents of this repository. Inside that container, we then call a shell scipt that runs Codecov's Bash uploader.
This repo is a GitHub Action, meaning it integrates with the GitHub Actions CI/CD pipeline. It's meant to take formatted reports with code coverage stats and upload them to codecov.io. Our Node action uses the Actions toolkit to make system calls that allow us to run Codecov's bash uploader inside of Node. Essentially what we're doing in this action is downloading Codecov's bash uploader script from codecov.io/bash, saving it as a file in the current directory, executing the file via `exec` calls, then removing the script from the current directory.
## PRs and Support
## PRs, Issues, and Support
Feel free to clone, modify code and request a PR to this repository. All PRs will be reviewed by the Codecov team. If your PR has been sitting for a while or if you have any questions, ping us at support@codecov.io
Feel free to clone, modify code and request a PR to this repository. All PRs and issues will be reviewed by the Codecov team. If your PR/issue has been sitting for a while or if you have any questions, ping us at support@codecov.io
### Easily upload coverage reports to Codecov from GitHub Actions
>The latest release of this Action adds support for tokenless uploads from GitHub Actions!
## Usage
To integrate Codecov with your Actions pipeline, specify the name of this repository with a tag number as a `step` within your `workflow.yml` file. This Action also requires you to [provide an upload token](https://docs.codecov.io/docs/frequently-asked-questions#section-where-is-the-repository-upload-token-found-) from [codecov.io](https://www.codecov.io) (tip: in order to avoid exposing your token, store it as a `secret`). Optionally, you can choose to include three additional inputs to customize the upload context.
To integrate Codecov with your Actions pipeline, specify the name of this repository with a tag number (`@v1` is recommended) as a `step` within your `workflow.yml` file.
If you have a *private repository*, this Action also requires you to [provide an upload token](https://docs.codecov.io/docs/frequently-asked-questions#section-where-is-the-repository-upload-token-found-) from [codecov.io](https://www.codecov.io) (tip: in order to avoid exposing your token, store it as a `secret`). Optionally, you can choose to include up to four additional inputs to customize the upload context. **For public repositories, no token is needed**
Inside your `.github/workflows/workflow.yml` file:
```yaml
steps:
- uses:actions/checkout@master
- uses:codecov/codecov-action@v1.0.3
- uses:codecov/codecov-action@v1
with:
token:${{secrets.CODECOV_TOKEN}}#required
file:./coverage.xml#optional
flags:unittests#optional
name:codecov-umbrella#optional
token:${{secrets.CODECOV_TOKEN}}# not required for public repos
files:./coverage1.xml,./coverage2.xml#optional
flags:unittests#optional
name:codecov-umbrella#optional
fail_ci_if_error:true# optional (default = false)
verbose:true# optional (default = false)
```
>**Note**: This assumes that you've set your Codecov token inside *Settings > Secrets* as `CODECOV_TOKEN`. If not, you can [get an upload token](https://docs.codecov.io/docs/frequently-asked-questions#section-where-is-the-repository-upload-token-found-) for your specific repo on [codecov.io](https://www.codecov.io).
>**Note**: This assumes that you've set your Codecov token inside *Settings > Secrets* as `CODECOV_TOKEN`. If not, you can [get an upload token](https://docs.codecov.io/docs/frequently-asked-questions#section-where-is-the-repository-upload-token-found-) for your specific repo on [codecov.io](https://www.codecov.io). Keep in mind that secrets are *not* available to forks of repositories.
## Arguments
Codecov's Action currently supports four inputs from the user: `token`, `file`, `flags`, and `name`. These inputs, along with their descriptions and usage contexts, are listed in the table below:
Codecov's Action currently supports five inputs from the user: `token`, `file`, `flags`,`name`, and `fail_ci_if_error`. These inputs, along with their descriptions and usage contexts, are listed in the table below:
| Input | Description | Usage |
| :---: | :---: | :---: |
| `token` | Used to authorize coverage report uploads | *Required* |
| `file` | Location of the coverage report | Optional
| `flags` | Flag upload under a certain group | Optional
| `token` | Used to authorize coverage report uploads | *Required for private repos* |
| `files` | Comma-separated paths to the coverage report(s) | Optional
| `directory` | Directory to search for coverage reports. | Optional
| `flags` | Flag the upload to group coverage metrics (unittests, uitests, etc.). Multiple flags are separated by a comma (ui,chrome) | Optional
| | |
| `aws_curl_args` | Extra curl arguments to communicate with AWS. | Optional
| `codecov_curl_args` | Extra curl arguments to communicate with Codecov. e.g., -U "--proxy http://http-proxy" | Optional
| `commit_parent` | The commit SHA of the parent for which you are uploading coverage. If not present, the parent will be determined using the API of your repository provider. When using the repository provider's API, the parent is determined via finding the closest ancestor to the commit. | Optional
| `env_vars` | Environment variables to tag the upload with. Multiple env variables can be separated with commas (e.g. `OS,PYTHON`) | Optional
| `fail_ci_if_error` | Specify if CI pipeline should fail when Codecov runs into errors during upload. *Defaults to **false*** | Optional
| | `network` Disable uploading the file network |
| | `recursesubs` Enable recurse submodules in git projects when searching for source files | |
| | `search` Disable searching for reports |
| | `xcode` Disable xcode processing |
| `gcov_path_include` | Paths to include during gcov gathering (as a glob) | Optional
| `gcov_args` | extra arguments to pass to gcov | Optional
| `gcov_executable` | gcov executable to run. Defaults to 'gcov' | Optional
| `gcov_path_exclude` | Paths to ignore during gcov gathering (as a glob) | Optional
| `gcov_prefix` | Prefix filepaths to help resolve path fixing | Optional
| `gcov_root_dir` | Project root directory, also used when preparing gcov | Optional
| `move_coverage_to_trash` | Move discovered coverage reports to the trash | Optional
| `name` | Custom defined name for the upload | Optional
| `override_branch` | Specify the branch name | Optional
| `override_build` | Specify the build number | Optional
| `override_commit` | Specify the commit SHA | Optional
| `override_pr` | Specify the pull request number | Optional
| `override_tag` | Specify the git tag | Optional
| `path_to_write_report` | Write upload file to path before uploading | Optional
| `root_dir` | Used when not in git/hg project to identify project root directory | Optional
| `verbose` | Specify whether the Codecov output should be verbose | Optional
| `working-directory` | Directory in which to execute `codecov.sh` | Optional
| `xcode_derived_data` | Custom Derived Data Path for Coverage.profdata and gcov processing | Optional
| `xcode_package` | Specify packages to build coverage. Uploader will only build these packages. This can significantly reduces time to build coverage reports. -J 'MyAppName' Will match "MyAppName" and "MyAppNameTests" -J '^ExampleApp$' Will match only "ExampleApp" not "ExampleAppTests" | Optional
### Example `workflow.yml` with Codecov Action
@@ -39,30 +81,44 @@ name: Example workflow for Codecov
description:'GitHub Action that uploads coverage reports for your repository to codecov.io'
author:'Ibrahim Ali <@ibrahim0814> | Codecov'
inputs:
name:
description:'User defined upload name. Visible in Codecov UI'
required:false
author:'Ibrahim Ali <@ibrahim0814> & Thomas Hu <@thomasrockhu> | Codecov'
inputs:
token:
description:'Repository upload token - get it from codecov.io'
required:true
file:
description:'Path to coverage file to upload'
description:'Repository upload token - get it from codecov.io. Required only for private repositories'
required:false
files:
description:'Comma-separated list of files to upload'
required:false
directory:
description:'Directory to search for coverage reports.'
required:false
flags:
description:'Flag upload to group coverage metrics (e.g. unittests | integration | ui,chrome)'
required:false
aws_curl_args:
description:'Extra curl arguments to communicate with AWS.'
required:false
codecov_curl_args:
description:'Extra curl arguments to communicate with Codecov. e.g., -U "--proxy http://http-proxy"'
required:false
commit_parent:
description:'The commit SHA of the parent for which you are uploading coverage. If not present, the parent will be determined using the API of your repository provider. When using the repository providers API, the parent is determined via finding the closest ancestor to the commit.'
required:false
env_vars:
description:'Environment variables to tag the upload with (e.g. PYTHON | OS,PYTHON)'
required:false
fail_ci_if_error:
description:'Specify whether or not CI build should fail if Codecov runs into an error during upload'
required:false
file:
description:'Path to coverage file to upload'
required:false
functionalities:
description:'Comma-separated list, see the README for options and their usage'
required:false
gcov_args:
description:'extra arguments to pass to gcov'
required:false
gcov_executable:
description:'gcov executable to run. Defaults to gcov'
required:false
gcov_path_exclude:
description:'Paths to ignore during gcov gathering (as a glob)'
required:false
gcov_path_include:
description:'Paths to include during gcov gathering (as a glob)'
required:false
gcov_prefix:
description:'Prefix filepaths to help resolve path fixing'
required:false
gcov_root_dir:
description:'Project root directory, also used when preparing gcov'
required:false
move_coverage_to_trash:
description:'Move discovered coverage reports to the trash'
required:false
name:
description:'User defined upload name. Visible in Codecov UI'
required:false
override_branch:
description:'Specify the branch name'
required:false
override_build:
description:'Specify the build number'
required:false
override_commit:
description:'Specify the commit SHA'
required:false
override_pr:
description:'Specify the pull request number'
required:false
override_tag:
description:'Specify the git tag'
required:false
path_to_write_report:
description:'Write upload file to path before uploading'
required:false
root_dir:
description:'Used when not in git/hg project to identify project root directory'
required:false
verbose:
description:'Specify whether the Codecov output should be verbose'
required:false
working-directory:
description:'Directory in which to execute codecov.sh'
required:false
xcode_derived_data:
description:'Custom Derived Data Path for Coverage.profdata and gcov processing'
required:false
xcode_package:
description:'Specify packages to build coverage. Uploader will only build these packages'
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
Tom Hu