docs: Document repository API token creation and scope OD-395 - #2725
Merged
Conversation
Contributor
|
Overall readability score: 53.81 (🟢 +0.02)
View detailed metrics🟢 - Shows an increase in readability
Averages:
View metric targets
|
Contributor
Up to standards ✅🟢 Issues
|
pedrobpereira
force-pushed
the
doc/repo-tokens-product-page-OD-395
branch
from
August 6, 2026 13:28
fd791d7 to
5234b79
Compare
pedrobpereira
force-pushed
the
doc/repo-tokens-product-page-OD-395
branch
from
August 6, 2026 13:32
5234b79 to
8b7d7ba
Compare
Cover name rules, mandatory 1-year expiry, the 13 allowed operations, and expired-token handling for repository tokens. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
pedrobpereira
force-pushed
the
doc/repo-tokens-product-page-OD-395
branch
from
August 6, 2026 13:35
8b7d7ba to
fdebbb4
Compare
LipeGheno
marked this pull request as ready for review
August 11, 2026 12:43
![codacy-production[bot]](https://avatars.githubusercontent.com/in/56611?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Pull Request Overview
The documentation updates generally align with the requirements for detailing Repository API token creation and scoping. However, the PR fails to document that token values remain fully visible (not masked) after creation, a detail explicitly mentioned in the PR intent. Additionally, the phrasing in some sections could lead to confusion between the restricted scope of API v3 tokens versus legacy API v2 behavior. Codacy results indicate the PR is up to standards with no new quality issues.
About this PR
- The PR description indicates that documentation would include a note about the token value staying 'fully visible after creation (not masked)', but this information is absent from the repository API tokens section.
Test suggestions
- Verify documentation of naming constraints for repository tokens.
- Verify documentation of the 1-year maximum expiration and absence of 'never-expire' option.
- Verify documentation of the 13 specific authorized operations for API v3.
- Verify documentation that legacy tokens without expiry are grandfathered.
- Verify mention of 'token value stays fully visible after creation (not masked)'
Prompt proposal for missing tests
Consider implementing these tests if applicable:
1. Verify mention of 'token value stays fully visible after creation (not masked)'
TIP Improve review quality by adding custom instructions
TIP How was this review? Give us feedback
- Repository token names are unique per repository (confirmed by Andrzej Janczak), not just character-restricted. - The Codacy Cloud CLI doesn't currently support repository tokens (confirmed by Andrzej Janczak) — the intro list implied it did for both token types. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
…D-395 Add screenshots for the repository API token flow: the create modal, the custom date option, the newly created token, the bulk delete, and a repository with a token that never expires. Replace the account API token screenshots, which no longer matched the UI. Correct the parts of the page the new screenshots contradicted: - Repository API tokens are under Settings > API tokens, not Integrations. - Account API tokens can no longer be created without an expiration date, and are capped at one year like repository tokens. - Tokens are revoked with the trash icon in the Actions column, or in bulk by selecting them and clicking Delete tokens. - Document that the token value is shown only once, immediately after creation. Add a recommendation to replace tokens without an expiration date, in both sections, including the order to follow so that live integrations don't break. Remove two images that no longer have any reference and no longer match the UI: codacy-api-tokens-account.png and codacy-api-tokens-repository.png. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
- The Codacy Cloud CLI does support repository API tokens since OD-489 shipped, so drop the claim that it doesn't. - Reword the notes on tokens created before expiration dates became mandatory, following Claudia's suggestion. - Turn the account-level note into a paragraph and the repository one back into a note, so the page keeps the same number of admonitions it had before the screenshots were added. - Stop blurring the token name in the never-expires screenshot: it's a generated name rather than a token value, and it was inconsistent with the bulk delete screenshot, which shows names unblurred. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Contributor
|
One open question, since it predates this PR and I couldn't settle it from screenshots: the account section still says "By hovering a token, you are able to copy its value." The account tokens table now masks the value ( |
Removing the claim that the CLI doesn't support repository API tokens left the documentation silent about it. Document it instead, now that OD-489 shipped in codacy-cloud-cli v1.9.0: - The option --repository-token and the CODACY_PROJECT_TOKEN environment variable, and that codacy login only takes account API tokens. - The precedence between the two tokens, the option, and stored credentials. - That commands outside the operations a repository API token authorizes fail immediately, and that codacy repository omits pull request and coverage data. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Per .claude/reference/formatting.md, checked against the docs-review-page rubric: - api-tokens.md: the two "replace grandfathered tokens" notes packed a 3-step sequence the reader must follow in order into one comma-chained sentence. Converted to a nested numbered list in both places, without adding an admonition, so the admonition count from the last round stays the same. - codacy-cloud-cli/index.md: split ## Authentication into ### Account API tokens and ### Repository API tokens, matching the ### subsection pattern already used by every other multi-topic section on this page (## What you can do, ## Example workflows). Moved "To remove your stored credentials" under Account API tokens, since codacy logout only applies to stored login credentials, not to a repository token passed via flag or env var. Verified with mkdocs build --strict: no broken anchors, no duplicate heading ids on the page. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
joanasteodoro
approved these changes
Aug 18, 2026
Codacy's AI reviewer flagged this on the original PR and it was never addressed: "Repository API tokens always have an expiration date" was already false the moment api-tokens.md documented that tokens created before expiration dates became mandatory keep working without one. Add "New" to scope the claim to newly created tokens, matching the reviewer's own suggested wording. The linked section already explains the grandfathered-token exception, so this stays a one-word fix rather than duplicating that explanation on a second page. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
4 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Changes
docs/codacy-api/api-tokens.md: document repository API token name rules, mandatory 1-year-max expiry (no never-expire option), that the token value stays fully visible after creation (not masked), grandfathered legacy tokens without an expiry, the distinct "token expired" error, and the full list of 13 operations a repository token can authorize (own repository only).docs/codacy-api/using-the-codacy-api.md: correct the auth section's outdated claim that all API v3 endpoints require an account token, and add a note on repository-token expiry/error behavior.👀 Live preview
https://doc-repo-tokens-product-page-od-395--docs-codacy.netlify.app
🚧 To do
Manual Testing
Add manual testing evidence here (steps, screenshots, environment).