From ba47d1915c08cc2e9b95edd2fe6c4bedaf096558 Mon Sep 17 00:00:00 2001 From: Fernandez Ludovic Date: Tue, 9 Dec 2025 06:49:56 +0100 Subject: [PATCH 1/2] docs: split install page --- README.md | 4 +- docs/content/docs/welcome/_index.md | 4 +- docs/content/docs/welcome/faq.md | 2 +- docs/content/docs/welcome/install/_index.md | 13 +++++ docs/content/docs/welcome/install/ci.md | 48 ++++++++++++++++ .../welcome/{install.md => install/local.md} | 57 ++++++------------- .../_shortcodes/golangci/latest-version.html | 9 ++- 7 files changed, 91 insertions(+), 46 deletions(-) create mode 100644 docs/content/docs/welcome/install/_index.md create mode 100644 docs/content/docs/welcome/install/ci.md rename docs/content/docs/welcome/{install.md => install/local.md} (89%) diff --git a/README.md b/README.md index e34bc2af2de0..c246286d33b9 100644 --- a/README.md +++ b/README.md @@ -13,8 +13,8 @@ integrates with all major IDEs, and includes over a hundred linters. ## Install `golangci-lint` -- [On my machine](https://golangci-lint.run/docs/welcome/install/#local-installation); -- [On CI/CD systems](https://golangci-lint.run/docs/welcome/install/#ci-installation). +- [On my machine](https://golangci-lint.run/docs/welcome/install/local); +- [On CI/CD systems](https://golangci-lint.run/docs/welcome/install/ci). ## Documentation diff --git a/docs/content/docs/welcome/_index.md b/docs/content/docs/welcome/_index.md index 3895e07973b3..525006e327c5 100644 --- a/docs/content/docs/welcome/_index.md +++ b/docs/content/docs/welcome/_index.md @@ -8,8 +8,8 @@ This quickstart guide provides step-by-step instructions to help you install, co {{< cards >}} - {{< card link="/docs/welcome/install/#local-installation" title="Local Installation" icon="archive" >}} - {{< card link="/docs/welcome/install/#ci-installation" title="CI Installation" icon="archive" >}} + {{< card link="/docs/welcome/install/local" title="Local Installation" icon="archive" >}} + {{< card link="/docs/welcome/install/ci" title="CI Installation" icon="archive" >}} {{< card link="/docs/welcome/integrations/" title="Integrations" icon="sparkles" >}} {{< card link="/docs/welcome/quick-start/#linting" title="Quick Start: Linting" icon="fast-forward" >}} {{< card link="/docs/welcome/quick-start/#formatting" title="Quick Start: Formatting" icon="fast-forward" >}} diff --git a/docs/content/docs/welcome/faq.md b/docs/content/docs/welcome/faq.md index e03026e85856..4fd40b9b0f45 100644 --- a/docs/content/docs/welcome/faq.md +++ b/docs/content/docs/welcome/faq.md @@ -19,7 +19,7 @@ some linters and/or internal pieces of golangci-lint could need to be adapted to Run golangci-lint in CI and check the exit code. If it's non-zero - fail the build. -See [how to properly install golangci-lint in CI](/docs/welcome/install/#ci-installation) +See [how to properly install golangci-lint in CI](/docs/welcome/install/ci) ## golangci-lint doesn't work diff --git a/docs/content/docs/welcome/install/_index.md b/docs/content/docs/welcome/install/_index.md new file mode 100644 index 000000000000..ed3a5d708a02 --- /dev/null +++ b/docs/content/docs/welcome/install/_index.md @@ -0,0 +1,13 @@ +--- +title: "Install" +weight: 1 +aliases: + - /welcome/install/ +--- + +Where do you want to install golangci-lint? + +{{< cards >}} + {{< card link="/docs/welcome/install/local" title="On my machine" icon="archive" >}} + {{< card link="/docs/welcome/install/ci" title="On CI/CD systems" icon="archive" >}} +{{< /cards >}} diff --git a/docs/content/docs/welcome/install/ci.md b/docs/content/docs/welcome/install/ci.md new file mode 100644 index 000000000000..287d1857adf4 --- /dev/null +++ b/docs/content/docs/welcome/install/ci.md @@ -0,0 +1,48 @@ +--- +title: "CI Installation" +weight: 3 +--- + +It's important to have reproducible CI: don't start to fail all builds at the same time. +With golangci-lint this can happen if you use option `linters.default: all` and a new linter is added +or even without `linters.default: all` when one upstream linter is upgraded. + +> [!IMPORTANT] +> It's highly recommended installing a specific version of golangci-lint available on the [releases page](https://github.com/golangci/golangci-lint/releases). + +## GitHub Actions + +We recommend using [our GitHub Action](https://github.com/golangci/golangci-lint-action) for running golangci-lint in CI for GitHub projects. + +It's [fast and uses smart caching](https://github.com/golangci/golangci-lint-action#performance) inside, +and it can be much faster than the simple binary installation. + +Also, the action creates GitHub annotations for found issues (you don't need to dig into build log to see found by golangci-lint issues). + +{{< cards cols=2 >}} + {{< golangci/image-card src="/images/colored-line-number.png" title="Console Output" >}} + {{< golangci/image-card src="/images/annotations.png" title="Annotations" >}} +{{< /cards >}} + +## GitLab CI + +GitLab provides a [guide for integrating golangci-lint into the Code Quality widget](https://docs.gitlab.com/ci/testing/code_quality/#golangci-lint). +A simple quickstart is their [CI component](https://gitlab.com/explore/catalog/components/code-quality-oss/codequality-os-scanners-integration), which can be used like this: + +```yaml {filename=".gitlab-ci.yml"} +include: + - component: $CI_SERVER_FQDN/components/code-quality-oss/codequality-os-scanners-integration/golangci@1.0.1 +``` + +Note that you [can only reference components in the same GitLab instance as your project](https://docs.gitlab.com/ci/components/#use-a-component) + +## Other CI + +Here are the other ways to install golangci-lint: + +{{< cards >}} + {{< card link="/docs/welcome/install/local/#binaries" title="Bash/Binaries" icon="archive" >}} + {{< card link="/docs/welcome/install/local/#docker" title="Docker" icon="archive" >}} +{{< /cards >}} + + diff --git a/docs/content/docs/welcome/install.md b/docs/content/docs/welcome/install/local.md similarity index 89% rename from docs/content/docs/welcome/install.md rename to docs/content/docs/welcome/install/local.md index d8f2b317305b..6b0824f38e65 100644 --- a/docs/content/docs/welcome/install.md +++ b/docs/content/docs/welcome/install/local.md @@ -1,8 +1,6 @@ --- -title: "Install" -weight: 1 -aliases: - - /welcome/install/ +title: "Local Installation" +weight: 2 --- ## CI installation @@ -42,20 +40,6 @@ include: Note that you [can only reference components in the same GitLab instance as your project](https://docs.gitlab.com/ci/components/#use-a-component) -### Buildkite - -Buildkite offers a [plugin](https://buildkite.com/resources/plugins/buildkite-plugins/golangci-lint-buildkite-plugin/) for running golangci-lint in Buildkite pipelines. - -It utilizes the official [Docker image](https://hub.docker.com/r/golangci/golangci-lint) by default, but can be set to use a binary if available on the agent. - -The plugin will annotate builds with results, providing an easily readable summary of fixes. - -```yaml {filename=".pipeline.yml"} -plugins: - - golangci-lint#v1.0.0: - config: .golangci.yml -``` - ### Other CI Here is the other way to install golangci-lint: @@ -73,31 +57,24 @@ wget -O- -nv https://raw.githubusercontent.com/golangci/golangci-lint/HEAD/insta golangci-lint --version ``` +On Windows, you can run the above commands with Git Bash, which comes with [Git for Windows](https://git-scm.com/download/win). + It is advised that you periodically update the version of golangci-lint as the project is under active development and is constantly being improved. For any problems with golangci-lint, check out recent [GitHub issues](https://github.com/golangci/golangci-lint/issues) and update if needed. -## Local Installation - -[![Packaging status](https://repology.org/badge/vertical-allrepos/golangci-lint.svg)](https://repology.org/project/golangci-lint/versions) - -### Binaries +## Linux -```bash -# binary will be $(go env GOPATH)/bin/golangci-lint -curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/HEAD/install.sh | sh -s -- -b $(go env GOPATH)/bin {{< golangci/latest-version >}} - -golangci-lint --version -``` +Golangci-lint is available inside the majority of the package managers. -On Windows, you can run the above commands with Git Bash, which comes with [Git for Windows](https://git-scm.com/download/win). +{{% details closed="true" title="Packaging status" %}} -### Linux +[![Packaging status](https://repology.org/badge/vertical-allrepos/golangci-lint.svg)](https://repology.org/project/golangci-lint/versions) -Golangci-lint is available inside the majority of the package managers. +{{% /details %}} -### macOS +## macOS -#### Homebrew +### Homebrew Note: Homebrew can use an unexpected version of Go to build the binary, so we recommend either using our binaries or ensuring the version of Go used to build. @@ -120,7 +97,7 @@ brew tap golangci/tap brew install golangci/tap/golangci-lint ``` -#### MacPorts +### MacPorts It can also be installed through [MacPorts](https://www.macports.org/) The MacPorts installation mode is community-driven and not officially maintained by the golangci team. @@ -129,9 +106,9 @@ The MacPorts installation mode is community-driven and not officially maintained sudo port install golangci-lint ``` -### Windows +## Windows -#### Chocolatey +### Chocolatey You can install a binary on Windows using [chocolatey](https://community.chocolatey.org/packages/golangci-lint). @@ -139,7 +116,7 @@ You can install a binary on Windows using [chocolatey](https://community.chocola choco install golangci-lint ``` -#### Scoop +### Scoop You can install a binary on Windows using [scoop](https://scoop.sh). @@ -149,7 +126,7 @@ scoop install main/golangci-lint The scoop package is not officially maintained by golangci team. -### Docker +## Docker ```bash docker run --rm -v $(pwd):/app -w /app golangci/golangci-lint:{{< golangci/latest-version >}} golangci-lint run @@ -170,7 +147,7 @@ docker run --rm -t -v $(pwd):/app -w /app \ golangci/golangci-lint:{{< golangci/latest-version >}} golangci-lint run ``` -### Install from Sources +## Install from Sources > [!WARNING] > Using `go install`/`go get`, "tools pattern", and `tool` command/directives installations aren't guaranteed to work. diff --git a/docs/layouts/_shortcodes/golangci/latest-version.html b/docs/layouts/_shortcodes/golangci/latest-version.html index 772bdd1b1350..3a04bdb9bf6e 100644 --- a/docs/layouts/_shortcodes/golangci/latest-version.html +++ b/docs/layouts/_shortcodes/golangci/latest-version.html @@ -5,4 +5,11 @@ @example {{< golangci/latest-version >}} */ -}} -{{- index $.Site.Data.version.version | default .Page.GitInfo.AbbreviatedHash | default "devel" -}} +{{- $v := index $.Site.Data.version.version -}} +{{- if $v -}} + {{- $v -}} +{{- else if .Page.GitInfo -}} + {{- .Page.GitInfo.AbbreviatedCommit -}} +{{- else -}} + devel +{{- end -}} From 21d0d9d914a805b3b810ebc60d8ec58fd2b07df2 Mon Sep 17 00:00:00 2001 From: Fernandez Ludovic Date: Wed, 10 Dec 2025 22:20:13 +0100 Subject: [PATCH 2/2] chore: buildkite --- docs/content/docs/welcome/install/ci.md | 16 +++++- docs/content/docs/welcome/install/local.md | 61 +--------------------- 2 files changed, 16 insertions(+), 61 deletions(-) diff --git a/docs/content/docs/welcome/install/ci.md b/docs/content/docs/welcome/install/ci.md index 287d1857adf4..fbb863c97d9c 100644 --- a/docs/content/docs/welcome/install/ci.md +++ b/docs/content/docs/welcome/install/ci.md @@ -36,6 +36,20 @@ include: Note that you [can only reference components in the same GitLab instance as your project](https://docs.gitlab.com/ci/components/#use-a-component) +## Buildkite + +Buildkite provides a [plugin](https://buildkite.com/resources/plugins/buildkite-plugins/golangci-lint-buildkite-plugin/) for running golangci-lint in Buildkite pipelines. + +It utilizes the [Docker image of golangci-lint](/docs/welcome/install/local/#docker) by default, but can be set to use a binary if available on the agent. + +The plugin will annotate builds with results, providing an easily readable summary of fixes. + +```yaml {filename=".pipeline.yml"} +plugins: + - golangci-lint#v1.0.0: + config: .golangci.yml +``` + ## Other CI Here are the other ways to install golangci-lint: @@ -44,5 +58,3 @@ Here are the other ways to install golangci-lint: {{< card link="/docs/welcome/install/local/#binaries" title="Bash/Binaries" icon="archive" >}} {{< card link="/docs/welcome/install/local/#docker" title="Docker" icon="archive" >}} {{< /cards >}} - - diff --git a/docs/content/docs/welcome/install/local.md b/docs/content/docs/welcome/install/local.md index 6b0824f38e65..d67cd6eb57f9 100644 --- a/docs/content/docs/welcome/install/local.md +++ b/docs/content/docs/welcome/install/local.md @@ -3,65 +3,6 @@ title: "Local Installation" weight: 2 --- -## CI installation - -Most installations of golangci-lint are performed for CI. - -It's important to have reproducible CI: don't start to fail all builds at the same time. -With golangci-lint this can happen if you use option `linters.default: all` and a new linter is added -or even without `linters.default: all` when one upstream linter is upgraded. - -> [!IMPORTANT] -> It's highly recommended installing a specific version of golangci-lint available on the [releases page](https://github.com/golangci/golangci-lint/releases). - -### GitHub Actions - -We recommend using [our GitHub Action](https://github.com/golangci/golangci-lint-action) for running golangci-lint in CI for GitHub projects. - -It's [fast and uses smart caching](https://github.com/golangci/golangci-lint-action#performance) inside, -and it can be much faster than the simple binary installation. - -Also, the action creates GitHub annotations for found issues (you don't need to dig into build log to see found by golangci-lint issues). - -{{< cards cols=2 >}} - {{< golangci/image-card src="/images/colored-line-number.png" title="Console Output" >}} - {{< golangci/image-card src="/images/annotations.png" title="Annotations" >}} -{{< /cards >}} - -### GitLab CI - -GitLab provides a [guide for integrating golangci-lint into the Code Quality widget](https://docs.gitlab.com/ci/testing/code_quality/#golangci-lint). -A simple quickstart is their [CI component](https://gitlab.com/explore/catalog/components/code-quality-oss/codequality-os-scanners-integration), which can be used like this: - -```yaml {filename=".gitlab-ci.yml"} -include: - - component: $CI_SERVER_FQDN/components/code-quality-oss/codequality-os-scanners-integration/golangci@1.0.1 -``` - -Note that you [can only reference components in the same GitLab instance as your project](https://docs.gitlab.com/ci/components/#use-a-component) - -### Other CI - -Here is the other way to install golangci-lint: - -```bash -# binary will be $(go env GOPATH)/bin/golangci-lint -curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/HEAD/install.sh | sh -s -- -b $(go env GOPATH)/bin {{< golangci/latest-version >}} - -# or install it into ./bin/ -curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/HEAD/install.sh | sh -s {{< golangci/latest-version >}} - -# In Alpine Linux (as it does not come with curl by default) -wget -O- -nv https://raw.githubusercontent.com/golangci/golangci-lint/HEAD/install.sh | sh -s {{< golangci/latest-version >}} - -golangci-lint --version -``` - -On Windows, you can run the above commands with Git Bash, which comes with [Git for Windows](https://git-scm.com/download/win). - -It is advised that you periodically update the version of golangci-lint as the project is under active development and is constantly being improved. -For any problems with golangci-lint, check out recent [GitHub issues](https://github.com/golangci/golangci-lint/issues) and update if needed. - ## Linux Golangci-lint is available inside the majority of the package managers. @@ -128,6 +69,8 @@ The scoop package is not officially maintained by golangci team. ## Docker +The Docker image is available on [Docker Hub](https://hub.docker.com/r/golangci/golangci-lint). + ```bash docker run --rm -v $(pwd):/app -w /app golangci/golangci-lint:{{< golangci/latest-version >}} golangci-lint run ```