semantic-release / semantic-release/docs

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

Open
#11 9 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
MDX
Stars
5
Forks
2
Avg merge
1d 15h
Merged PRs (30d)
7

Description

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?

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Review ci-configuration.md and the linked GitHub Actions, CircleCI, GitLab CI, Travis CI, and Jenkins recipe pages. Start by resolving the maintainer questions about service lists, semantic-release-cli references, authentication guidance, and recipe scope. Done means the agreed documentation changes, current links, supported versions, and valid examples are reflected consistently across the pages.

Written by the indexing model from the issue text.

Assessment

Tech stack
github-actions, node.js, yaml
Domain
ci-cd, documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Needs clarification
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.