refactor(ci-configuration): enhance documentation for clarity and action#12
Conversation
…led setup instructions Co-authored-by: Copilot <copilot@github.com>
…nks for consistency
…examples from the main instruction
…y and consistency Co-authored-by: Copilot <copilot@github.com>
…est execution section for clarity
… guidance for unsupported services Co-authored-by: Copilot <copilot@github.com>
…I service selection Co-authored-by: Copilot <copilot@github.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
…ons for clarity and structure Co-authored-by: Copilot <copilot@github.com>
… clarity Co-authored-by: Copilot <copilot@github.com>
| | ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ||
| | `GH_TOKEN` or `GITHUB_TOKEN` | A GitHub [personal access token](https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line). | | ||
| | `GL_TOKEN` or `GITLAB_TOKEN` | A GitLab [personal access token](https://docs.gitlab.com/ce/user/profile/personal_access_tokens.html). | | ||
| | `GH_TOKEN` or `GITHUB_TOKEN` | A GitHub [personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens). _Note: In GitHub Actions, `GITHUB_TOKEN` is automatically provided by the runner._ | |
There was a problem hiding this comment.
it could be a good idea to link from here to the docs in the readme of the github plugin repo. the permissions needed for the pipeline token are outlined there (but could probably benefit from a refresh to be more clear about preferring the pipeline token or github app auth over a PAT and that the only reason something more than the pipeline token should be needed is for making a commit during the release process, but that we discourage that)
There was a problem hiding this comment.
Preference note we can definitely add, pointing to only use PAT when its only required (don't know how to phrase that 😆)
...and Yes, be good to link to the github plugin... I'll find a good place
Does something similar exist for GitLab?
There was a problem hiding this comment.
Does something similar exist for GitLab?
i'm not a user of gitlab, so i havent done a good job of adding similar guidance for it when i've made updates for github. if the plugin readme lacks details that we would otherwise want to point to from here, we may need to ask for assistance
There was a problem hiding this comment.
another detail that comes up in support a fair amount is the node runtime for running in ci. it is natural for teams to assume they are blocked from updating to our latest versions because they need to run the rest of their ci workflow with a lower version of node, so we often need to clarify for folks that most ci platforms support defining a different node version for the part of their workflow that does the release compared to the rest of the workflow. i think we touch on this in the node version doc, but it would probably worth guiding them to that information from this doc.
additionally, because our recommended installation approach is through npx, we could guide folks to the idea that they dont even need a package.json in their project if they dont otherwise need one. this is a common confusion point, especially for folks using semantic-release for languages other than javascript. this topic is less related to ci config, but is related enough that i thought it was worth mentioning in case it helps tie the various ideas together somehow
There was a problem hiding this comment.
Yea... sounds like something that can go under the "Run semantic-release only after all tests succeeded"... But I struggle to actually work how to let this in without messing with the requirements message this page documents.
It sounds like something for a running semantic-release page, as much as it touches the configuring CI.
What do you suggest as course of action or should we move this forward? 🤔
There was a problem hiding this comment.
maybe its best to capture this as a follow up rather than try to include it in this PR. once we get this one merged, we may have better insight for where it fits best
|
for ci services that we dont define specific recipes for, i wonder if there would be value in directing folks to https://github.com/semantic-release/env-ci/ for some details about what semantic-release is looking for on their provider 🤔 |
Yea... though we might not have a recipe for their CI, this still communicates support for their various CI environment... Bet a line as simple should do.... added to the note for unlisted ci service recipe
|
…uctions and add details on environment variables
…g trusted publishing and registry support
… for clarity and security
… for authentication
… variable details
…on for authentication Co-authored-by: Copilot <copilot@github.com>
…y publishing Co-authored-by: travi <126441+travi@users.noreply.github.com>
Co-authored-by: Matt Travi <126441+travi@users.noreply.github.com>
2 participants
This pull request updates the CI configuration documentation for
semantic-releaseto provide a clearer, more structured guide for configuring CI services and authentication. The page now directs users to specific CI recipes, clarifies authentication requirements, and improves links and explanations for environment variable setup.Notable Changes
Documentation structure and clarity:
ci-configuration.md) now starts with a summary of the two main requirements: running semantic-release only after all tests pass, and configuring authentication. It introduces a new "Choose your CI service" section with direct links to our recipes for popular CI services.getting-started.mdx) step for CI setup has been expanded to reference the new CI recipe section and provide clearer sub-steps for choosing a CI guide, ensuring correct job ordering, and setting up authentication.Authentication guidance updates:
Related Issue
Screenshot/Screencast
screen-capture.webm