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.
Connect Codecov to Mattering
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
A Codecov call works against a public repository, so the token must be fine
List Member Login Sessions returns a permission error
The file coverage node returns 404 for a path that definitely exists
A comparison node returns a 400
Compare Impacted Files returns an empty files list
A downstream template resolves to nothing on components, the report tree, or a comparison
Coverage numbers look stale or a new commit is missing
An upload token ended up somewhere it should not be
Related
The Codecov MCP
What connecting Codecov unlocks for AI agents and automations, with common uses and FAQs.
More guides
All Automations documentation
Every integration guide, plus how connectors, credentials, and workflows fit together.
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.