docs: add personal access token docs

[jyecusch]

Adds docs about creating and using Personal Access Tokens with the CLI and API, as well as notes on how to use them in CI/CD workflows.

[coderabbitai]

📝 Walkthrough

Walkthrough

Removed the CLI documentation page at docs/cli/access-token.mdx and updated docs/docs.json to remove the CLI entry and add two new guide pages: docs/guides/personal-access-tokens.mdx and docs/guides/cicd-authentication.mdx. Added two new guide files covering Personal Access Tokens (creation, management, security, expiration) and CI/CD authentication workflows (platform-specific setup, token usage with CLI, Docker, and API examples). No code or public API changes.

Possibly related PRs

• docs: fix issues with layout and content found during review #53: Edits the same file docs/cli/access-token.mdx which this PR deletes.
• Adds install card to CLI introduction and Reorders nav #58: Modifies docs/docs.json navigation including the cli/access-token entry removed here.

Suggested labels

released

Suggested reviewers

• raksiv
• tjholm
• sean-nitric
• HomelessDinosaur

Pre-merge checks

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title Check	✅ Passed	The PR title "docs: add personal access token docs" directly summarizes the primary change in the changeset. The pull request adds two new documentation guides focused on Personal Access Tokens (personal-access-tokens.mdx and cicd-authentication.mdx) while removing the previous CLI access-token documentation. The title is concise, clear, and accurately reflects the main objective of adding PAT documentation.
Description Check	✅ Passed	The PR description accurately describes the changeset as adding documentation about creating and using Personal Access Tokens with CLI and API, plus CI/CD workflow guidance. This directly aligns with the additions of personal-access-tokens.mdx and cicd-authentication.mdx. The description is clearly on-topic and sufficiently related to the changes made.

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 04f8e39 and 5c24c5a.

⛔ Files ignored due to path filters (3)

• docs/images/personal-access-tokens/generate-personal-access-tokens-modal.png is excluded by !**/*.png
• docs/images/personal-access-tokens/personal-access-tokens-settings-page.png is excluded by !**/*.png
• docs/images/personal-access-tokens/token-created-modal.png is excluded by !**/*.png

📒 Files selected for processing (4)

• docs/cli/access-token.mdx (0 hunks)
• docs/docs.json (1 hunks)
• docs/guides/cicd-authentication.mdx (1 hunks)
• docs/guides/personal-access-tokens.mdx (1 hunks)

💤 Files with no reviewable changes (1)

• docs/cli/access-token.mdx

✅ Files skipped from review due to trivial changes (1)

• docs/guides/personal-access-tokens.mdx

🚧 Files skipped from review as they are similar to previous changes (1)

• docs/docs.json

🧰 Additional context used

🪛 Gitleaks (8.28.0)

docs/guides/cicd-authentication.mdx

[high] 325-325: Discovered a potential authorization token provided in a curl command header, which could compromise the curl accessed resource.

(curl-auth-header)

🔇 Additional comments (4)

docs/guides/cicd-authentication.mdx (4)

1-36: Security guidance is appropriate.

The documentation correctly emphasizes secure token handling by recommending CI/CD platform secrets management and explicitly warning against committing tokens to repositories.

---

38-260: Platform-specific setup is comprehensive, but GitLab deploy stage appears to duplicate build logic.

Lines 128–129 show the deploy stage calling suga build instead of a deployment-specific command (e.g., suga deploy). Verify this is intentional or update to reflect the actual deployment workflow.

---

320-348: API authentication examples are clear.

The Bearer token usage across curl, JavaScript, and Python is correct. Note: Gitleaks flagged line 325 as a potential auth token, but this is a false positive—your placeholder (your-token-here) is appropriately generic for documentation.

---

1-355: Verify internal links and referenced installation URL.

Several cross-references need verification:

• Internal links: /guides/personal-access-tokens, /cli, /cli/config, /cli/build
• Installation URL: https://addsuga.com/install (referenced in lines 72, 115, 170, 228)

Additionally, the overview mentions BitBucket Pipelines (line 14) but provides no setup example. Consider either adding it or removing it from the list.

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between dc31eb0 and 04f8e39.

⛔ Files ignored due to path filters (3)

• docs/images/personal-access-tokens/generate-personal-access-tokens-modal.png is excluded by !**/*.png
• docs/images/personal-access-tokens/personal-access-tokens-settings-page.png is excluded by !**/*.png
• docs/images/personal-access-tokens/token-created-modal.png is excluded by !**/*.png

📒 Files selected for processing (4)

• docs/cli/access-token.mdx (0 hunks)
• docs/docs.json (1 hunks)
• docs/guides/cicd-authentication.mdx (1 hunks)
• docs/guides/personal-access-tokens.mdx (1 hunks)

💤 Files with no reviewable changes (1)

• docs/cli/access-token.mdx

🧰 Additional context used

🪛 Gitleaks (8.28.0)

docs/guides/cicd-authentication.mdx

[high] 325-325: Discovered a potential authorization token provided in a curl command header, which could compromise the curl accessed resource.

(curl-auth-header)

🔇 Additional comments (4)

docs/docs.json (1)

33-34: Navigation structure looks good. The two new guides are properly positioned in the "Guides" group and will be discoverable from the main docs navigation.

docs/guides/cicd-authentication.mdx (1)

320-348: API authentication examples are clear and appropriate. The gitleaks alert on line 325 is a false positive—this is documentation showing how to use bearer tokens with placeholder text, not an actual credential. The examples are well-structured and properly demonstrate API usage patterns.

docs/guides/personal-access-tokens.mdx (2)

1-140: Overall structure and guidance are solid. The guide provides comprehensive coverage of PAT creation, security best practices, and token management. The step-by-step workflow is clear, and the security emphasis (warnings about treating tokens like passwords, rotation policies) is appropriate. Subject to verification of the API authentication reference and image assets.

---

37-40: All image assets confirmed in place. All three PNG files referenced in the personal access tokens workflow documentation exist at the specified paths in /images/personal-access-tokens/.

[raksiv]

Generated the key using the staging application.
Tested the key for commands locally and ran the APIs from the guide.

[nitric-bot]

🎉 This PR is included in version 0.4.1 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀