CI Configuration page & recipes: outdated content, dead links, and dead services

[babblebey]

The CI Configuration page is linked from step 2 of Getting Started. It references several dead CI services and has outdated links. The linked recipe pages range from recently updated (GitHub Actions) to significantly broken (GitLab CI).

Dead/Concerning CI services listed on the main page

The CI services list in ci-configuration.md includes:

Service	Status
Codeship	Dead. Acquired by CloudBees, then sunset. Link redirects to CloudBees docs.
Wrecker	Dead. Acquired by Oracle, then discontinued. Link returns HTTP error.

GitHub Actions, CircleCI, Travic CI, GitLab CI, GoCD and Codefresh are still active. Travis CI Free tier for OSS removed in 2020-2021.

Proposal: Remove Codeship and Wercker (clear-cut dead).

Question for maintainers: Do we want to keep GoCD and Codefresh in the list on the main page? Neither has a recipe page. They're just bullet-point links. My inclination is to trim the list to the services we actually have recipes for (GitHub Actions, CircleCI, GitLab CI, Jenkins).

Recipe pages by condition

GitHub Actions - good shape

Recently updated with trusted publishing, provenance, setup-node warning. One minor issue though: the persist-credentials example still uses actions/checkout@v2 while the rest of the page uses @v4.

CircleCI - dated but functional

• Node version examples use 14 and 16 (both EOL), should be updated to current LTS versions
• References semantic-release-cli

GitLab CI - significantly broken

• All examples use Node 10 and 12 (EOL since 2021/2022)
• package.json example pins semantic-release: ^15.0.0
• The "all projects" config has two YAML jobs both named release: - duplicate keys, so the config is technically invalid
• Links use old GitLab URL conventions (/ce/ prefix, README.html extensions)

Travis CI - dated but functional

• Example uses outdated Node/Go versions and old semantic-release versions.

Jenkins CI - minor issues

• Double period (..) at end of Jenkins settings link
• semantic-release: ^18.0.0 in package.json example
• References semantic-release-cli
• Otherwise reasonable

Outdated links on the main CI configuration page

Several external links use old URL formats that currently redirect but should be updated:

• help.github.com/articles/creating-a-personal-access-token-for-the-command-line → should point to docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens
• docs.gitlab.com/ce/user/profile/personal_access_tokens.html → old /ce/ path
• docs.npmjs.com/getting-started/working_with_tokens and docs.npmjs.com/getting-started/using-two-factor-authentication → old npm docs paths

semantic-release-cli references

Multiple recipe pages reference semantic-release-cli for easy setup of NPM_TOKEN and GH_TOKEN. This tool appears unmaintained.

Question for maintainers: Should we remove all semantic-release-cli references? If so, should we replace them with brief manual instructions, or just drop the lines entirely since the main CI config page already explains how to set the env vars?

Other content concerns

The main page's plugin auth table says GH_TOKEN only supports "personal token" authentication. This is misleading now that:

• GitHub Actions auto-populates GITHUB_TOKEN
• Trusted publishing via OIDC is the recommended approach for npm

Question for maintainers: Should we expand the auth section to mention GITHUB_TOKEN in Actions and trusted publishing here, or keep this page focused on manual token setup and leave the details to the GitHub Actions recipe?

[travi]

GitHub Actions - good shape

one thing we are overdue for documenting a better recommendation for is in this section (and i think some other areas that i'm not finding immediately). we really should avoid recommending the use of a personal access token for commits during release. we already recommend against making commits when they can be avoided, which is a good step, but we dont give the best guidance when someone decides they should make commits anyway. the best option for us to recommend is a little more complicated, but with the proper docs to provided guidance, would be what i think is reasonable. instead of a PAT, we should be recommending the use of github app auth something like https://github.com/actions/create-github-app-token.

also, once we've documented that, it would be good for us to exercise the recommendation in the repo for our git plugin. as much as we recommend against making commits, that workflow should be a reference example

[travi]

GitLab CI

we also need to highlight trusted publishing in this context. @fgreinacher and @JonasSchubert, maybe even @tachyons might be willing to help review the gitlab docs

[travi]

• docs.npmjs.com/getting-started/working_with_tokens and docs.npmjs.com/getting-started/using-two-factor-authentication → old npm docs paths

there is probably some directional guidance we should make consistent around tokens with npm. in general, we should be guiding folks toward trusted publishing instead of using long-lived tokens in ci at all

[travi]

example still uses actions/checkout@v2 while the rest of the page uses @v4

for situations like these, it would probably be worth configuring some custom managers for renovate so it can keep versions fresh for us automatically

[travi]

The main page's plugin auth table says GH_TOKEN only supports "personal token" authentication. This is misleading now that:

• GitHub Actions auto-populates GITHUB_TOKEN
• Trusted publishing via OIDC is the recommended approach for npm

Question for maintainers: Should we expand the auth section to mention GITHUB_TOKEN in Actions and trusted publishing here, or keep this page focused on manual token setup and leave the details to the GitHub Actions recipe?

i think trusted publishing is separate from talking about github tokens, but i do think there is value in explaining the options around tokens better. we support GH_TOKEN and GITHUB_TOKEN, but there are behavioral differences. i think the main difference is classic PAT vs granular/app token, but i'm not even super confident. like mentioned above, we should guide folks to use github app tokens since they are short lived and automatically rotated, but mentioning the existence of alternatives is ok, especially if we touch on the downsides of those alternatives.

ideal, dont make commits, so use the pipeline token. next, if commits are required, use github app auth. not recommended: classic PAT or granular PAT stored as secret

[travi]

Multiple recipe pages reference semantic-release-cli for easy setup of NPM_TOKEN and GH_TOKEN. This tool appears unmaintained.

Question for maintainers: Should we remove all semantic-release-cli references? If so, should we replace them with brief manual instructions, or just drop the lines entirely since the main CI config page already explains how to set the env vars?

yeah, we made a decision a while back not to include that in the path to onboarding for folks anymore. it would be appropriate to remove any remaining mentions from the docs and we should probably archive the repo

[babblebey]

we should probably archive the repo

Will do.

for situations like these, it would probably be worth configuring some custom managers for renovate so it can keep versions fresh for us automatically

This will automatically update the docs, I guess

there is probably some directional guidance we should make consistent around tokens with npm. in general, we should be guiding folks toward trusted publishing instead of using long-lived tokens in ci at all

How would you suggest we place this guide? I believe we can note on this page that trusted publishing is now the preferred approach where supported, but where do we place the details about it? The RECIPES pages??

---

I will work on this CI Configuration page to start with, we will get to the single recipe page for the CI in follow-up PRs

[travi]

How would you suggest we place this guide? I believe we can note on this page that trusted publishing is now the preferred approach where supported, but where do we place the details about it? The RECIPES pages??

after reading through your updates to the ci config page, i think that page is probably the right place to give the general guidance. for service specific details, like using github app auth instead of a PAT for pushing commits, i think the github actions recipe is the place to go into those more concrete details

[babblebey]

I'm keeping this Issue opened to track the CI Configuration Recipes