Codecov

Code coverage done right.®

Welcome to Codecov Documentation. You'll find comprehensive guides and documentation to help you start working with Codecov as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started
Suggest Edits

Authorization

 

To access Codecov's API as an authenticated user please create an access token in Codecov. To create an access token please follow these directions:

  1. Navigate to your account page by clicking on your avatar (top right corner) then Account
  2. Click on Access tab
  3. Click on Create in the API Tokens panel
  4. Type in a token name and click Generate
  5. Use this token in your API requests as stated below.

You can pass the token in the query params or in the request headers as seen in the two examples below.

GET https://codecov.io/api/{gh}/{owner}/{repo}?access_token={token}
curl -X GET https://codecov.io/api/{gh}/{owner}/{repo} \
     -H 'Authorization: token {token}' 
Suggest Edits

Pagination

 

Resources that return variable length of data will be paginated. Page and number of entries are stated in the meta as seen below.

{
  "meta": {
    "status": 200,
    "limit": 20,
    "page": 1
  }
}

To request more pages please append the query param page like this:

GET /api/gh/:owner/:repo/commits?page=2

You can also limit the number of entries like this:

GET /api/gh/:owner/:repo/pulls?limit=1

Many Codecov responses include a totals object. The format of this object is outlined below.

{
  "totals": {
    "c": "70.00000",  // coverage ratio
    "f": 2,			      // files count
    "n": 10,          // lines count
    "h": 7,           // hits count
    "m": 2,           // missed count
    "p": 1,           // partials count
    "b": 3,           // branches count
    "d": 0,           // methods count
    "M": 0,           // messages count
    "s": 3            // sessions count
  }
}

In the case of comparing commits, a diff array may also be returned, It is defined as follows:

"diff": [
1,					//files count
0, 					//lines count
0,					//hits count
0,					//misses count
0,					//partials count
null,					//coverage (null or number)
0,					//branches count
0,					//methods count
0,					//messages count
0,					//sessions count
null,					//complexity (null or number)
null,					//complexity_total (null or number)
,0],				//diff

The coverage, complexity, and complexity_total values will be null if the diff contains a lines count of zero.

Many Codecov responses include an authors object. The format of this object is outlined below.

{
  "author": {
    "service": "github",
    "name": "Gafsi",
    "email": "hello@codecov.io",
    "username": "codecov",
    "service_id": "12345"
  }
}

List teams

GET /api/gh

Get a single team

GET /api/gh/:owner
Suggest Edits

Repositories

 

List repositories

GET /api/gh/:owner
{
  "repos": [
     {
      "fork": null,
      "name": "repo-name",
      "language": null,
      "cache": {
        "yaml": "codecov.yml",
        "commit": {
          "author": {
            "username": "<redacted>",
            "service_id": "<redacted>",
            "name": "<redacted>",
            "service": "<redacted>",
            "email": "<redacted>"
          },
          "timestamp": "2018-10-08T02:50:34",
          "totals": [
            //array of coverage totals
          ],
          "commitid": "<commit-id>",
          "ci_passed": null,
          "message": "Commit Message"
        }
      },
      "activated": true,
      "private": true,
      "updatestamp": "1970-01-01 00:00:00.000000+00:00",
      "latest_commit": "1970-01-01 00:00:00",
      "branch": "<branch>",
      "coverage": 100.00,
      "upload_token": "<redacted>",
      "repoid": "<redacted>"
    }
  ]
}

Get a single repository

GET /api/gh/:owner/:repo
 

List branches

GET /api/gh/:owner/:repo/branches

Get a single branch

GET /api/gh/:owner/:repo/branch/:branch

Delete a branch

DELETE /api/gh/:owner/:repo/branch/:branch

An HTTP 204 is returned if successful.

Suggest Edits

Pull Requests

 

List pull requests

Each returned pull request will include the pull request base and head commits. Pagination applied.

GET /api/gh/:owner/:repo/pulls

Parameters

Param
Description

state

Filter the list of pulls returned based on the pull request state determined by the service provider.
Choose: all, open, closed, merged. Default: open

sort

Sort the query results.
Choose: pullid, impact, updatestamp. Default: pullid

order

Specify the sorting order.
Choose: desc, asc. Default: desc

Result

{
  "pulls": [
    {
      "pullid": 1915,
      "author": "<author obj>",
      "title": "pull request title",
      "updatestamp": "2016-08-19 14:38:26.970575+00:00",
      "state": "open",
      "diff": "<totals obj>",
      "totals": {
        "base": "<totals obj>",
        "head": "<totals obj>"
      },
      "head": {
        "message": "tip of pull request commit message",
        "totals": "<totals obj>",
        "ci_passed": true,
        "timestamp": "2016-08-19 14:26:02",
        "commitid": "df150e4be50ae09263107c3ea43d1a35f055bb71",
        "author": "<author obj>"
      },
      "base": {
        "message": "pull request base commit message",
        "totals": "<totals obj>",
        "ci_passed": true,
        "timestamp": "2016-08-17 22:22:32",
        "commitid": "010e063270be37cfa8547ccfb9717e5d874c88a8",
        "author": "<author obj>"
      }
    }
  ]
}

Get a single pull request

GET /api/gh/:owner/:repo/pull/1
 

List commits

GET /api/gh/:owner/:repo/commits

Parameters

Param
Type

from

any date and/or time string

Only query commits starting from this date

to

any date and/or time string

Only query commits up to this date

Results

{
  "commits": [
    {
      "branch": "master",
      "merged": null,
      "message": "pretty commit message",
      "deleted": null,
      "totals": "<totals obj>",
      "pullid": null,
      "ci_passed": true,
      "commitid": "30eb4733ba830d48b02a90285950c9b4db48c35d",
      "timestamp": "2016-08-18 17:32:25",
      "author": "<auther obj>"
    }
  ]
}

Get a single commit

GET /api/gh/:owner/:repo/commit/:sha

Force notifications to run

POST /api/gh/:owner/:repo/commit/:sha

This endpoint will force the commit to run the notification job and update the internal commit state.

Compare two commits

GET /api/gh/:owner/:repo/compare/:base...:head

Get folder totals

GET /api/gh/:owner/:repo/tree/:ref/:path
{
  "commit": {
    "folder_totals": <totals obj>
  }
}

Delete a commit

Deleting a commit will remove the commit from Codecov permanently.

DELETE /api/gh/:owner/:repo/commit/:sha

A HTTP 204 is returned if successful.

Upload versions 1 and 3 are depreciated.

Upload query - as seen as `$query` below

Argument
Required
Description

commit

Yes

The destination commit sha for the report.

token

Yes

A UUID token used to identify the project.

branch

No

The target branch for the report. This value may be overridden during the Codecov discovery process.

build

No

The build number provided by your CI service.

job

No

The job number provided by your CI service.

build_url

No

The http url to link back to your CI provider.

name

No

A custom name for this specific upload.

slug

No

The owner/repo slug name of the project.

yaml

No

The relative path to the codecov.yml in this project.

service

No

The CI service name. See below for acceptable values.

flags

No

Used for Flags. Can be one or more flags. E.g., flags=unit or flags=unit,java

pr

No

The pull request number this commit is currently found in.

List of acceptable CI service names.

[
  "travis",
  "buildbot",
  "circleci",
  "buddybuild",
  "solano",
  "teamcity",
  "appveyor",
  "wercker",
  "magnum",
  "shippable",
  "codeship",
  "drone.io",
  "jenkins",
  "semaphore",
  "gitlab",
  "bamboo",
  "snap",
  "buildkite",
  "bitrise",
  "greenhouse",
  "custom"
]

Acceptable report formats

Codecov processes reports server side and accepts every report format we have come across over the years. Below is a list of acceptable coverage report formats.

  • Clover XML
  • Cobertura XML
  • [Default JSON]
  • Coveralls JSON
  • SharpCover XML
  • D-Lang coverage reports
  • FlowCover
  • Gap-Lang coverage reports
  • Gcov
  • Go-Lang coverage reports
  • Jacoco XML
  • Lcov
  • Lua-Lang coverage reports
  • Mono Coverage XML
  • Istanbul JSON
  • R-Lang coverage reports
  • Ruby JSON
  • Scala XML
  • Scoverage XML
  • VB coverage XML
  • llvm coverage
  • and more (we say this because there are more)

Uploaded report content - as seen as `@reports` below

The uploaded content can be any number of coverage report formats wrapped up into the same file.

touch reports
cat coverage.xml >> reports
echo '<<<<<< EOF' >> reports
cat lcov.info >> reports
echo '<<<<<< EOF' >> reports

The resulting file at reports will look like the following.

<?xml version="1.0" encoding="UTF-8" ?>
<coverage>
  ..data..
</coverage>
<<<<<< EOF
TN:
SF:file.js
..data..
<<<<<< EOF

Codecov JSON report format

Below is a very simple json coverage report that can be used if you are building a custom format.

{
  "coverage": {
    "filename": {
      "1": 0,      # line 1 missed
      "2": 1,      # line 2 hit once
      "3": "1/2",  # line 3 partial hit, one missing branch
      "4": "1/3",  # line 4 partial hit, two missing branches
					         # skip line 5
      "6": null,   # skip line 6
      "7": 5       # line 7 hit 5 times
    }
  }
}

Have more details you would like to provide? No problem. Please contact support to learn about our advanced report json documentation.

Version 2 - Direct upload

Upload v2 is used to upload report contents directly to Codecov. The reports are included in the upload body.

curl -X POST \
  --data-binary @reports \
  "https://codecov.io/upload/v2?${query}"

Version 4 - Upload to S3

Version 4 is recommended because it uploads and archives the reports to S3 immediately. Codecov web server will not get the report data directly, which can cause issues server other web request if the file size it large.

# tell codecov we have an upload
res=$(curl -sX POST -H 'Accept: text/plain' "https://codecov.io/upload/v4?${query}")

cc_url=$(echo "$res" | sed -n 1p)  # where the reports will end up in Codecov UI
s3_url=$(echo "$res" | sed -n 2p)  # this url is temporary. it will expire

# upload reports to s3
curl -fisX PUT --data-binary @reports \
  -H 'Content-Type: text/plain' \
  -H 'x-amz-acl: public-read' \
  -H 'x-amz-storage-class: REDUCED_REDUNDANCY' \
  "$s3_url"

echo "View reports at $cc_url"

Version 5 - Fetched

Version 5 is used when the report can be downloaded at a url. Codecov will fetch the report at time of processing.

reports="https://company.com/assets/coverage/..."
curl -X POST \
  --data-binary $reports \
  "https://codecov.io/upload/v5?${query}&url=${reports}"
Suggest Edits

About Graphs

 
 

The coverage sunburst is a graph of the project in a multi-level pie chart. The color represents the coverage of the project, folder, and files. The innermost circle is the entire project the next slices are folders leading to the outermost slices which are files.

HTML

From your project dashboard you will find an interactive sunburst graph.

Click slices to zoom in. Click center to zoom out. `shit+click` to navigate to a file in Codecov.

Click slices to zoom in. Click center to zoom out. shit+click to navigate to a file in Codecov.

SVG

# tip of default branch
GET /gh/:owner/:repo/graphs/sunburst.svg?token=:graph_token

# tip of branch
GET /gh/:owner/:repo/branch/:branch/graphs/sunburst.svg?token=:graph_token

# tip of pull
GET /gh/:owner/:repo/pull/:id/graphs/sunburst.svg?token=:graph_token

# specific commit
GET /gh/:owner/:repo/commit/:sha/graphs/sunburst.svg?token=:graph_token
<object data="https://codecov.io/gh/docker/notary/branch/master/graphs/sunburst.svg" type="image/svg+xml"></object>

Result

Below is an example SVG output.

Parameters

Param
Default

width

300

height

300

border_size

1

border_color

white

The tree graph is a block style layout of your repository. Each block represents a single file in the repository. The size of each block is the number of covered statements and methods in the file. The color is based on that files coverage. Each block includes a link to the file, which you may click to redirect to the file.

# tip of default branch
GET /gh/:owner/:repo/graphs/tree.svg?token=:graph_token

# tip of branch
GET /gh/:owner/:repo/branch/:branch/graphs/tree.svg?token=:graph_token

# tip of pull
GET /gh/:owner/:repo/pull/:id/graphs/tree.svg?token=:graph_token

# specific commit
GET /gh/:owner/:repo/commit/:sha/graphs/tree.svg?token=:graph_token

Click on a file below to navigate to the file's coverage in Codecov.

<object data="https://codecov.io/gh/docker/notary/branch/master/graphs/tree.svg" type="image/svg+xml"></object>

Parameters

Provide query arguments to customize the graph.

Param
Default

width

500

height

500

border_size

1

border_color

white

The icicle graph exposes your project in a top down approach. The top slice is the entire project. Each child slice, moving down, is a folder leading to the files themselves. The size of each slice is the sum of the covered lines. The color is the based on that slices coverage ratio.

# tip of default branch
GET /gh/:owner/:repo/graphs/icicle.svg?token=:graph_token

# tip of branch
GET /gh/:owner/:repo/branch/:branch/graphs/icicle.svg?token=:graph_token

# tip of pull
GET /gh/:owner/:repo/pull/:id/graphs/icicle.svg?token=:graph_token

# specific commit
GET /gh/:owner/:repo/commit/:sha/graphs/icicle.svg?token=:graph_token
<object data="https://codecov.io/gh/docker/notary/graphs/icicle.svg" type="image/svg+xml"></object>

Parameters

Provide query arguments to customize the graph.

width

700

height

150

border_size

1

border_color

white

Suggest Edits

Repository Settings

 

Activate Repository

POST /api/gh/:owner/:repo/settings
BODY action=activate

Deactivate Repository

POST /api/gh/:owner/:repo/settings
BODY action=deactivate

Regenerate Upload Token

POST /api/gh/:owner/:repo/settings
BODY action=regenerate