Menu

Mattering Automations Codecov integration

Connect Codecov to Mattering Automations: coverage totals and line-by-line reports, repositories, branches, commits and uploads, pull requests with patch coverage, flags and components, coverage trends, six comparison nodes, ingested test runs, and organization members as workflow steps, authenticated with one personal access token.

The Mattering Automations Codecov integration adds the Codecov API v2 to your automation canvas: read coverage totals and full line-by-line reports, roll coverage up to the directory tree or narrow it to one file, list repositories, branches, commits and the individual uploads behind each commit, read pull requests with their patch coverage, list flags and components, chart coverage trends over a date range, compare two commits or a whole pull request by file, flag, component or segment, read the test runs Codecov has ingested, and manage organization membership.

The credential is a Codecov personal access token, generated in your own Codecov account settings under Access and sent as an Authorization bearer header on every request to api.codecov.io. There are no scopes to choose and no documented OAuth app flow for API v2, so the token is the whole credential. Codecov documents it as a personal account token rather than a per repository or per organization credential, so treat it as carrying its creator's access, which is the single most important thing to decide before you paste one into an automation. Setup takes a few minutes, and this guide walks through each step and ends with the full node reference.

The safety modeling is the shape of the API itself. Of the 33 nodes, 32 read and 1 acts, and none are destructive: Codecov: Set Member Activation is the only write Codecov API v2 exposes, it flips one boolean, and the opposite call restores it. One read still deserves care for a different reason. Codecov: Get Repository Upload Tokens returns credential material, and anyone holding a repository's upload token can post coverage reports for that repository, so treat that node's output like the secret it contains rather than like data.

Before you start

  • A Codecov account you can sign in to, connected to the git service whose repositories you want to read. Every path in this API starts with that service, and the nodes default it to github.
  • A personal access token generated from your Codecov account settings. Codecov documents it as a personal account token rather than a per repository or per organization credential, so treat it as carrying its creator's access, and if your team separates duties, consider creating it from a dedicated service account rather than an individual's login.
  • At least one repository that has received a coverage upload from your CI. This integration reads coverage; it does not produce it, and the v2 API exposes no upload endpoint. A repository that has never been uploaded to reads back with null totals rather than zero.
  • A Mattering workspace with access to the Automations app.
  • Worth knowing before you troubleshoot: Codecov serves public repository data without any credential at all. A call against a public repository can return real rows when no token is sent, so a green result there is not proof that a credential was configured. The verify path below uses the owner listing for exactly that reason.
  • API access itself is listed on every Codecov plan, including the free tier, so the connector authenticates the same way on any account. Some of the data behind it is plan gated: flags, components and carryforward flags are paid-plan features on Codecov's pricing page, with flaky test detection higher still, and on a free account those nodes tend to return empty results rather than an error, which reads like a broken node. Private repositories consume a seat licence, and the free tier is limited to one such user and a capped number of private uploads per month. Check your plan before concluding a node is broken.

Generate your Codecov access token

Mattering authenticates to Codecov with a personal access token, sent as an Authorization bearer header on every request. Codecov API v2 documents one security scheme and no OAuth app flow, so there is nothing to scope and nothing to approve: the token simply is your API identity. That is what makes the next paragraph matter more than the click path.

Sign in at codecov.io, open the avatar menu, then Settings, then Access.
Click Generate Token, name it something that identifies this integration, and copy the token.
Codecov documents this as a personal account token rather than a per repository or per organization credential, so treat it as carrying its creator's access: a token pasted into an automation is as powerful as the person who created it. For shared or long-lived workflows, generate it from a dedicated service account with only the access those workflows need, and never commit it to version control.
A Codecov upload token is a different credential. Upload tokens are per repository and let CI post coverage reports; they will not authenticate this integration. If a credential that looks right keeps failing, check that you copied an access token from the Access page rather than a repository upload token.

Connect Codecov to Mattering

In Mattering Automations, open Connectors and click Add Connector.
Choose Codecov from the list.
Click Create new credential, paste the access token, and save.
The credential is stored encrypted in Google Secret Manager and never appears in workflow logs.
Click Test Connection. Mattering calls Codecov's owner listing for the git service, which is deliberately account scoped: it returns 401 with no header and 401 with an invalid token, so a pass here really does prove the credential.
The connection test is not a repository read on purpose. Codecov serves public repository data unauthenticated, so a repository probe would pass with no credential at all and tell you nothing about the token you just stored.
Click Connect. All 33 Codecov nodes appear in your canvas palette.

Verify it works

After connecting, open any automation canvas and check the palette: a Codecov section should list the query nodes and the single action node. Drop Codecov: List Owners onto the canvas and run a test step. It is the integration's natural probe, the same call the connection test makes, and it takes only the git service. Copy a username from the result, because the owner field on every other node expects exactly that value.

Next, run Codecov: List Repositories with that username and note the shape: paginated listers return a page envelope, so the rows sit at data.results[] and the repository name is at data.results[].name. Then run Codecov: Get Coverage Totals against a repository your CI uploads to; with no commit or branch named it reads the head of the default branch, which is the headline coverage number and the fastest confirmation that real data is flowing. Everything in this verify path is read-only, so it is safe to re-run whenever you rotate the token.

Node reference

33 nodes, generated from the connector itself so this reference always matches what ships.

Read and query nodes 32

Codecov: Compare Commits

codecov_compare_commits

Compare coverage between two commits, or across a pull request. Supply the base and head SHAs together, OR a pull request number, but not both. Returns base, head and patch totals, the per-file comparison, the git commits in the range, and any files present in the diff that coverage does not track.

Codecov: Compare Components

codecov_compare_components

Compare coverage per COMPONENT between two commits or across a pull request, so a change can be attributed to the part of the codebase it touched. Supply base and head SHAs together, OR a pull request number. The response is a BARE ARRAY, so output paths start at data[].

Codecov: Compare Evaluations

codecov_compare_evals

Compare AI evaluation runs between two commits, returning the base summary, the head summary and the difference between them, so a change in pass rate, cost or score is attributable to a specific commit. Codecov publishes no response schema for this endpoint, so the sample below was captured from a live call.

Codecov: Compare File Coverage

codecov_compare_file

Compare ONE file between two commits or across a pull request, returning every line of the file with its base and head coverage and whether the line is part of the diff. The name field is an object with base and head entries, because a file can be renamed between the two commits. Supply base and head SHAs together, OR a pull request number.

Codecov: Compare File Segments

codecov_compare_segments

The same file comparison narrowed to the SEGMENTS a change touched, instead of every line in the file. Use it when a large file would otherwise drown the useful part of the diff. An unaffected file returns an empty segment list. Supply base and head SHAs together, OR a pull request number.

Codecov: Compare Flags

codecov_compare_flags

Compare coverage per FLAG between two commits or across a pull request, which is how you tell that unit coverage held while integration coverage fell. Supply base and head SHAs together, OR a pull request number. The response is a BARE ARRAY, so output paths start at data[]. A flag with no base report comes back with null base totals rather than being omitted.

Codecov: Compare Impacted Files

codecov_compare_impacted_files

The precomputed version of the commit comparison, listing only the files a change actually affected. It computes asynchronously: a state of pending means the files are still being worked out and the files list is empty, and processed means it is ready, so poll rather than reading it once. Supply base and head SHAs together, OR a pull request number.

Codecov: Get Branch

codecov_get_branch

Fetch one branch by name. The response embeds the branch's current head commit, including that commit's coverage totals and its full report, so this is the cheapest way to answer 'what is coverage on this branch right now'.

Codecov: Get Commit

codecov_get_commit

Fetch one commit by SHA, including its coverage totals and its full per-file report. The processing state tells you whether Codecov has finished with it: complete, pending, error or skipped.

Codecov: Get Coverage Report

codecov_get_commit_report

The coverage totals node plus LINE BY LINE coverage for every file, where each entry pairs a line number with 0 for hit, 1 for miss and 2 for partial. A whole repository's line data is a large payload, so filter by path prefix, flag or component unless you genuinely need all of it.

Codecov: Get Coverage Report Tree

codecov_get_report_tree

Coverage rolled up to the directory tree, matching the repository's folder structure, with lines, hits, partials and misses at each level. Returns only the top level by default; raise the depth or start from a sub-path to go deeper. The response is a BARE ARRAY, so output paths start at data[].

Codecov: Get Coverage Totals

codecov_get_commit_totals

Coverage totals for one commit, plus the same totals broken down file by file. Defaults to the head of the default branch; name a SHA or a branch to target another commit, and narrow with a path prefix, a flag or a component. This is the headline number node.

Codecov: Get Coverage Trend

codecov_get_coverage_trend

Coverage over time for a repository, as a paginated series of buckets one day, one week or one month wide. Each bucket carries the minimum, maximum and average coverage inside it. One behaviour to plan for: when there is no measurement on the start date, Codecov prepends a single measurement from BEFORE the start date so the value can be carried forward, so the first row may fall outside the range you asked for.

Codecov: Get Evaluation Summary

codecov_get_evals_summary

Summarise the AI evaluation runs uploaded for a repository: how many items ran, how many passed and failed, the average duration and cost, and the scores by name. Narrow to one commit, or to one grouping such as a test class, a vitest describe block or a langfuse run name. Codecov publishes no response schema for this endpoint, so the sample below was captured from a live call.

Codecov: Get File Coverage

codecov_get_file_report

Coverage for ONE file: its totals, its line-by-line values and a link to the file on Codecov. Defaults to the head of the default branch; name a SHA or a branch for another commit. Missing coverage for the path comes back as a 404 rather than an empty report.

Codecov: Get Flag Coverage Trend

codecov_get_flag_coverage_trend

Coverage over time for ONE flag, as a paginated series of buckets one day, one week or one month wide, each carrying the minimum, maximum and average coverage inside it. Use it to watch a single suite, for example whether integration coverage is drifting while the overall number holds. As with the repository trend, a measurement from before the start date may be prepended so the value can be carried forward.

Codecov: Get Organization Member

codecov_get_user

Fetch one member of a Codecov organization by username or by numeric owner id, returning their display name, email, admin flag and activation state.

Codecov: Get Owner

codecov_get_owner

Fetch one organization or user account by name, returning its service, username and display name. Useful as a cheap check that a name is spelled the way Codecov holds it before running a heavier repository or coverage read.

Codecov: Get Pull Request

codecov_get_pull

Fetch one pull request by its number, with base and head coverage totals and the patch coverage of the change. Use it to gate a merge automation on whether the new lines are covered.

Codecov: Get Repository

codecov_get_repo

Fetch one repository by name, returning its default branch, language, private and active flags, and the most recent coverage totals on the default branch. Totals come back null for a repository that has never received an upload.

Codecov: Get Repository Upload Tokens

codecov_get_repo_config

Fetch a repository's upload token and graph token. The response is CREDENTIAL MATERIAL: the upload token lets any holder post coverage reports for that repository. Treat the output like a secret and do not pipe it into a message, a log or a stored record.

Codecov: List Branches

codecov_list_branches

List a repository's branches with the time each was last updated, most recently updated first. Busy repositories carry thousands of branches, so page through rather than expecting one call to cover them.

Codecov: List Commit Uploads

codecov_list_commit_uploads

List every coverage upload Codecov received for one commit, with each upload's flags, CI provider, build URL, processing state and its own totals. This is the node that answers 'is a shard missing' when a commit's coverage looks lower than expected.

Codecov: List Commits

codecov_list_commits

List a repository's commits, newest first, each with its message, author, branch, CI pass flag, Codecov processing state and coverage totals. Filter to one branch to follow a single line of work.

Codecov: List Components

codecov_list_components

List a repository's components with each component's current coverage. Components are the path groupings defined in codecov.yml, so this is the per-area coverage breakdown. The response is a BARE ARRAY with no page envelope, so output paths start at data[].

Codecov: List Flags

codecov_list_flags

List a repository's coverage flags with each flag's current coverage percentage. Flags are the labels attached to uploads in codecov.yml, typically one per test suite or per runtime.

Codecov: List Member Login Sessions

codecov_list_user_sessions

List login sessions for the members of a Codecov organization, with each member's name, whether they hold an active session, and when it expires. The caller must be an admin of the requested organization; anyone else gets a permission error rather than an empty list.

Codecov: List Organization Members

codecov_list_users

List the members of a Codecov organization, with each member's username, display name, email, admin flag and whether they are activated. Filter by activation state, by admin state, or by a search term over the name.

Codecov: List Owners

codecov_list_owners

List every organization and user account on one git service that the stored token can reach. This is the starting point for every other node here: the username it returns is what the owner field elsewhere expects. It is also the connector's auth probe, because it is the cheapest call that genuinely requires a valid token.

Codecov: List Pull Requests

codecov_list_pulls

List a repository's pull requests as Codecov sees them, each with its title, author, state, CI pass flag, base and head coverage totals, and the patch coverage of the change itself. Patch coverage is the number a review actually cares about.

Codecov: List Repositories

codecov_list_repos

List an owner's repositories with their default branch, primary language, private flag and most recent coverage totals. Filter to repositories that have received an upload, to an explicit list of names, or by a search term.

Codecov: List Test Results

codecov_list_test_analytics

List individual test runs Codecov has ingested for a repository, each with its name, class, suite, framework, outcome, duration, flags and failure message. Filter to failures on a branch to build a flake report, or filter by duration to find the slow tests. This replaces the retired test-results endpoint, which now only redirects here.

Action nodes 1

Codecov: Set Member Activation

codecov_update_user_activation

Activate or deactivate one member of a Codecov organization. Activation is the only writable field on the whole v2 API. Deactivating removes that person's access to the organization's Codecov data and releases the seat they occupied; the opposite call restores both, which is why this is reversible rather than destructive.

Using the integration

On the automation canvas

Codecov nodes chain with every other node: a git webhook can run Codecov: Get Pull Request and branch on the patch coverage before deciding whether to comment or open a review task, a scheduled sweep can write Codecov: Get Coverage Trend rows into a Mattering database, and Codecov: List Test Results can turn a night of failures into one task with the failure messages attached. Two values feed almost everything downstream: the username from Codecov: List Owners and the repository name from Codecov: List Repositories. The git service is a path segment on every node rather than a setting, defaulted to github.

From AI assistants over MCP

Every node speaks MCP, the open protocol for connecting AI assistants to tools, so Claude, ChatGPT, and Matter can drive the same surface. The read nodes are a large and safe surface to hand an agent: it can answer why coverage fell by reading Codecov: Get Commit, checking whether a shard is missing with Codecov: List Commit Uploads, and attributing the change with Codecov: Compare Flags and Codecov: Compare Components. Only one node changes anything at all, Codecov: Set Member Activation, so the usual guidance about gating destructive tools mostly does not apply here; the exception to gate is Codecov: Get Repository Upload Tokens, because of what it returns rather than what it does.

Patch coverage is the number worth automating on

Total coverage moves slowly, which is why a pull request can add uncovered code without visibly changing it. Codecov: Get Pull Request and Codecov: List Pull Requests both return base and head totals alongside the patch coverage of the change itself, and Codecov: Compare Commits gives the same picture addressed by SHAs, including the files present in the diff that coverage does not track at all. One addressing rule runs through the whole comparison family: supply base and head SHAs together, or a pull request number, but not both. Each comparison node says so in its description, because the alternative is a bare 400 with nothing to explain it.

Narrowing a comparison before it gets large

Codecov: Compare Impacted Files is the precomputed shortlist of files a change affected, and it computes asynchronously: a state of pending means the list is still being worked out and the files array is empty, processed means it is ready, so poll rather than reading it once. Codecov's reference does not describe that lifecycle, so the node documents it as behaviour observed through the connector rather than a vendor guarantee. From there Codecov: Compare File Coverage returns every line of one file with base and head values, and Codecov: Compare File Segments returns only the segments the change touched, which is what keeps a large file from drowning the useful part of the diff. The file name in a comparison is an object with base and head entries rather than a string, because files get renamed between two commits.

Reading coverage without pulling the whole repository

Codecov: Get Coverage Totals is the headline number node, with the same totals broken down file by file. Codecov: Get Coverage Report adds line-by-line coverage for every file, where each entry pairs a line number with 0 for hit, 1 for miss and 2 for partial, and a whole repository of line data is a large payload, so filter by path prefix, flag or component unless you genuinely need all of it. Codecov: Get Coverage Report Tree is the middle ground, rolling coverage up to the folder structure and returning only the top level until you raise the depth. Codecov: Get File Coverage is the single-file read; a path with no coverage comes back as a 404 rather than an empty report.

Trends, bucket width, and the carry-forward row

Codecov: Get Coverage Trend and Codecov: Get Flag Coverage Trend return coverage over time as buckets, each carrying the minimum, maximum and average inside it. Bucket width is a required parameter chosen per request, one day, seven days or thirty days, so a daily job and a quarterly report read the same endpoint at different resolutions. Thirty days is a fixed stride rather than a calendar month, so the buckets drift against month boundaries over a long range and a calendar-month report has to regroup them locally. The date range is a real start and end pair, so a scheduled refresh can advance its window rather than re-fetching fixed dates forever. One behaviour to handle comes from observation against the live API rather than from vendor documentation. When there is no measurement on the start date, Codecov prepends a single measurement from before it so the value can be carried forward, so the first row may fall outside the range you asked for. Drop it or file it in the previous period, but do not count it inside the window.

Three response shapes, and why templates break

Codecov returns three different top-level shapes and the connector passes them through exactly as sent rather than flattening them, so output paths tell the truth. Paginated listers return a page envelope, so rows are at data.results[]. Single-resource reads return a bare object, so fields are at data.something. And four endpoints return a bare array with no envelope at all: Codecov: List Components, Codecov: Get Coverage Report Tree, Codecov: Compare Components and Codecov: Compare Flags, whose rows are at data[]. Each node's sample output shows which shape it uses; when a downstream template resolves to nothing, that mismatch is the first thing to check.

Membership, sessions, and the one write

Codecov: List Organization Members reports who is in an organization with their admin flag and activation state, filterable by activation, by admin, or by a search over the name, and Codecov: Get Organization Member fetches one. Codecov: Set Member Activation is the whole write surface of this integration: deactivating releases the seat that person occupied and removes their access to the organization's coverage metrics, and the opposite call restores both, which makes it a natural last step in an offboarding workflow. Codecov: List Member Login Sessions shows who holds an active session and when it expires, with one access rule of its own: the caller must be an admin of the organization being asked about.

Troubleshooting

Test Connection fails with 401 Invalid token
Codecov returns 401 with a detail of Invalid token when the bearer token is not one it recognises, and 401 with a detail about missing authentication credentials when no header arrives at all. Both point at the credential rather than the workspace. Check for leading or trailing whitespace from the copy, confirm the token has not been revoked or regenerated in Codecov since you saved it, and confirm you pasted an access token from the Access page rather than a repository upload token, which authenticates a different thing entirely.
A Codecov call works against a public repository, so the token must be fine
It is not proof of anything, and this trips people up often enough to be worth stating plainly. Codecov serves public repository data unauthenticated: a request for a public organization's repositories returns real rows with no Authorization header. So a green result from a public-repo read tells you the network path works, not that the stored credential does. Note the narrow case this covers: an invalid bearer token is rejected with a 401 even on a public repository, so what a passing public-repo read really hides is the situation where no Authorization header reaches Codecov at all. Use the owner listing instead, which is exactly what Test Connection calls and why: it is the cheapest call that genuinely requires a valid token. If the owner listing passes and a private repository still fails, the problem is what that token's owner can see in Codecov, not the connector.
List Member Login Sessions returns a permission error
That endpoint requires the caller to be an admin of the organization being asked about, and Codecov returns a permission error rather than an empty list when they are not. Confirm the token's owner is an admin of that organization, or run the workflow with a token from someone who is. Note the difference from an empty result: a permission error means the request was refused, while an empty results array means the organization genuinely has no sessions matching. Codecov: List Organization Members needs no admin rights and is the right node when you only need the roster.
The file coverage node returns 404 for a path that definitely exists
Two causes, and they look identical from the outside. First, a trailing slash is absorbed into the path value, so a request for a file path ending in a slash asks Codecov for a file whose name ends in a slash and gets a 404 with the path echoed back; send the path with no trailing slash. Second, this node needs the file's exact path as coverage recorded it, not a directory or a prefix, and coverage that was never recorded for that file is a 404 rather than an empty report. Read Codecov: Get Coverage Totals first and take the path from its per-file breakdown. The path field on the totals, report and tree nodes is a different thing again: there it is a prefix filter, not a file identifier.
A comparison node returns a 400
The comparison family takes either-or addressing: base and head SHAs together, or a pull request number, but never both and never neither. All three fields are optional in the schema because exactly one pairing is required, which means the validation happens at Codecov rather than in the form, and a missing or mixed pairing surfaces as a 400. Pick one mode per node and template only that mode's fields. This applies to every comparison node: Codecov: Compare Commits, Codecov: Compare Components, Codecov: Compare Flags, Codecov: Compare File Coverage, Codecov: Compare Impacted Files and Codecov: Compare File Segments.
Compare Impacted Files returns an empty files list
Check the state field before treating that as an answer. This node is precomputed asynchronously: while Codecov is still working it out, the response carries a state of pending and an empty files array, and only a state of processed means the list is complete. Codecov's reference does not describe that lifecycle, so it is documented on the node as behaviour observed through the connector rather than a vendor guarantee. A workflow should poll with a short wait between attempts rather than reading it once and concluding nothing changed. If the state reads processed and the list is still empty, the comparison genuinely found no impacted files, which is the normal result for a change that touched nothing coverage tracks.
A downstream template resolves to nothing on components, the report tree, or a comparison
Almost always the page envelope assumption. Most Codecov listers return the paginated envelope with rows at data.results[], but four endpoints return a bare array instead: Codecov: List Components, Codecov: Get Coverage Report Tree, Codecov: Compare Components and Codecov: Compare Flags. Their rows sit at data[], so a path written as data.results[].component_id resolves to nothing while data[].component_id works. The connector deliberately does not normalise these into one shape, because each node's sample output documents the real one and flattening them would make the canvas output paths lie. Check the node's sample output when a path comes back empty.
Coverage numbers look stale or a new commit is missing
Separate the two layers before debugging the workflow. Codecov: Get Commit reports a processing state of complete, pending, error or skipped, so a commit that exists with pending coverage is simply not finished, and a commit missing entirely usually means CI never uploaded for it. Codecov: List Commit Uploads is the node that settles it, showing every upload received for that commit with its CI provider, build URL and state, which is how a missing shard reveals itself as coverage that looks unexpectedly low. The one piece of vendor guidance for genuinely stale repository or branch data is operational: signing in to Codecov re-triggers a sync with your code provider.
An upload token ended up somewhere it should not be
Codecov: Get Repository Upload Tokens is a read that changes nothing, but its response is credential material: the repository's upload token and graph token. Codecov's own reference calls the underlying endpoint Repository config, operation repos_config_retrieve, which is what to search for in their docs rather than upload tokens. Anyone holding the upload token can post coverage reports for that repository. Treat the node's output the way you would treat a secret, which means not piping it into a chat message, a log line, a task description or a stored database record by reflex. If one has already leaked, rotate it in Codecov and re-check which workflows reference that node. The safer default is to leave this node out of any workflow whose output a person or an assistant will read.

Codecov is a trademark of its respective owner. Mattering uses platform names to identify the services these integrations connect to; no endorsement or affiliation is implied.

Start Free Explore our Products