Add Vale checks to project
- Adds error-only configution. - Makes check part of CI pipeline. - Fixes errors in content.
This commit is contained in:
Evan Read
Marcel Amirault
parent
7b133f65db
commit
9a73f9fbb2
|
|
@ -0,0 +1,9 @@
|
|||
# Vale configuration file.
|
||||
#
|
||||
# For more information, see https://errata-ai.gitbook.io/vale/getting-started/configuration.
|
||||
|
||||
StylesPath = doc/.vale
|
||||
MinAlertLevel = suggestion
|
||||
|
||||
[*.md]
|
||||
BasedOnStyles = gitlab
|
||||
|
|
@ -0,0 +1,11 @@
|
|||
---
|
||||
# Checks that internal links have .md extenstion and not .html extension.
|
||||
#
|
||||
# For a list of all options, see https://errata-ai.github.io/vale/styles/
|
||||
extends: existence
|
||||
message: Link %s must use the .md file extension.
|
||||
link: https://docs.gitlab.com/ee/development/documentation/styleguide.html#links-to-internal-documentation
|
||||
level: error
|
||||
scope: raw
|
||||
raw:
|
||||
- '\[.+\]\((https?:){0}[\w\/\.-]+(\.html).*\)'
|
||||
|
|
@ -0,0 +1,11 @@
|
|||
---
|
||||
# Checks for the presence of absolute hyperlinks that should be relative.
|
||||
#
|
||||
# For a list of all options, see https://errata-ai.github.io/vale/styles/
|
||||
extends: existence
|
||||
message: Link %s must be relative.
|
||||
link: https://docs.gitlab.com/ee/development/documentation/styleguide.html#links-to-internal-documentation
|
||||
level: error
|
||||
scope: raw
|
||||
raw:
|
||||
- '\[.+\]\(https?:\/\/docs\.gitlab\.com\/omnibus.*\)'
|
||||
|
|
@ -0,0 +1,15 @@
|
|||
---
|
||||
# Checks for the following in common content scenarios:
|
||||
#
|
||||
# - No spaces.
|
||||
# - More than one space.
|
||||
#
|
||||
# For a list of all options, see https://errata-ai.github.io/vale/styles/
|
||||
extends: existence
|
||||
message: '"%s" must contain one and only one space.'
|
||||
link: https://docs.gitlab.com/ee/development/documentation/styleguide.html#punctuation
|
||||
level: error
|
||||
nonword: true
|
||||
tokens:
|
||||
- '[a-z][.?!,][A-Z]'
|
||||
- '[\w.?!,\(\)\-":] {2,}[\w.?!,\(\)\-":]'
|
||||
|
|
@ -0,0 +1,13 @@
|
|||
---
|
||||
# Checks for use of some of the top misused terms at GitLab.
|
||||
#
|
||||
# For a list of all options, see https://errata-ai.github.io/vale/styles/
|
||||
extends: substitution
|
||||
message: Use "%s" instead of "%s".
|
||||
link: https://about.gitlab.com/handbook/communication/#top-misused-terms
|
||||
level: error
|
||||
ignorecase: true
|
||||
swap:
|
||||
GitLabber: GitLab team member
|
||||
self hosted: self-managed
|
||||
self-hosted: self-managed
|
||||
|
|
@ -33,9 +33,9 @@ This section describes the commonly used configuration settings. Check
|
|||
|
||||
- [Installing GitLab](https://about.gitlab.com/install/)
|
||||
- [Manually downloading and installing a GitLab package](manual_install.md)
|
||||
- [Setting up a domain name/URL](https://docs.gitlab.com/omnibus/settings/configuration.html#configuring-the-external-url-for-gitlab) for the GitLab Instance so that it can be accessed easily
|
||||
- [Enabling HTTPS](https://docs.gitlab.com/omnibus/settings/nginx.html#enable-https)
|
||||
- [Enabling notification emails](https://docs.gitlab.com/omnibus/settings/smtp.html#smtp-settings)
|
||||
- [Setting up a domain name/URL](settings/configuration.md#configuring-the-external-url-for-gitlab) for the GitLab Instance so that it can be accessed easily
|
||||
- [Enabling HTTPS](settings/nginx.md#enable-https)
|
||||
- [Enabling notification emails](settings/smtp.md#smtp-settings)
|
||||
- [Enabling replying via email](https://docs.gitlab.com/ee/administration/reply_by_email.html#set-it-up)
|
||||
- [Installing and configuring postfix](https://docs.gitlab.com/ee/administration/reply_by_email_postfix_setup.html)
|
||||
- [Enabling container registry on GitLab](https://docs.gitlab.com/ee/administration/packages/container_registry.html#container-registry-domain-configuration)
|
||||
|
|
@ -74,8 +74,8 @@ to work best with the available resources. Check out the [documentation](setting
|
|||
- [Changing the name of the Git user group](settings/configuration.md#changing-the-name-of-the-git-user--group)
|
||||
- [Specify numeric user and group identifiers](settings/configuration.md#specify-numeric-user-and-group-identifiers)
|
||||
- [Only start Omnibus GitLab services after a given filesystem is mounted](settings/configuration.md#only-start-omnibus-gitlab-services-after-a-given-filesystem-is-mounted)
|
||||
- [Disable user and group account management](settings/configuration.html#disable-user-and-group-account-management)
|
||||
- [Disable storage directory management](settings/configuration.html#disable-storage-directories-management)
|
||||
- [Disable user and group account management](settings/configuration.md#disable-user-and-group-account-management)
|
||||
- [Disable storage directory management](settings/configuration.md#disable-storage-directories-management)
|
||||
- [Configuring Rack attack](settings/configuration.md#configuring-rack-attack)
|
||||
- [SMTP](settings/smtp.md)
|
||||
- [NGINX](settings/nginx.md)
|
||||
|
|
|
|||
|
|
@ -161,7 +161,7 @@ The cache mechanism can be summarised as follows:
|
|||
1. If cache has been dirtied, break the loop.
|
||||
1. Else, checkout the snapshot.
|
||||
1. If there are remaining dependencies:
|
||||
1. For each remaining dependency:
|
||||
1. For each remaining dependency:
|
||||
1. Build the dependency.
|
||||
1. Create a snapshot and commit it.
|
||||
1. Push back the new build cache to CI cache.
|
||||
|
|
|
|||
|
|
@ -222,7 +222,7 @@ Keep in mind that the Git user must have access to the system so please review
|
|||
your security settings at `/etc/security/access.conf` and make sure the Git user
|
||||
is not blocked.
|
||||
|
||||
## Postgres error 'FATAL: could not create shared memory segment: Cannot allocate memory'
|
||||
## Postgres error `FATAL: could not create shared memory segment: Cannot allocate memory`
|
||||
|
||||
The packaged Postgres instance will try to allocate 25% of total memory as
|
||||
shared memory. On some Linux (virtual) servers, there is less shared memory
|
||||
|
|
@ -245,7 +245,7 @@ postgresql['shared_buffers'] = "100MB"
|
|||
|
||||
Run `sudo gitlab-ctl reconfigure` for the change to take effect.
|
||||
|
||||
## Postgres error 'FATAL: could not open shared memory segment "/PostgreSQL.XXXXXXXXXX": Permission denied'
|
||||
## Postgres error `FATAL: could not open shared memory segment "/PostgreSQL.XXXXXXXXXX": Permission denied`
|
||||
|
||||
By default, Postgres will try to detect the shared memory type to use. If you don't
|
||||
have shared memory enabled, you might see this error in `/var/log/gitlab/postgresql/current`.
|
||||
|
|
@ -380,7 +380,7 @@ Redis, Mattermost) are isolated from each other using Unix user
|
|||
accounts. Creating and managing these user accounts requires root
|
||||
access. By default, Omnibus GitLab will create the required Unix
|
||||
accounts during `gitlab-ctl reconfigure` but that behavior can be
|
||||
[disabled](../settings/configuration.html#disable-user-and-group-account-management).
|
||||
[disabled](../settings/configuration.md#disable-user-and-group-account-management).
|
||||
|
||||
In principle Omnibus GitLab could do with only 2 user accounts (one
|
||||
for GitLab and one for Mattermost) if we give each application its own
|
||||
|
|
@ -618,7 +618,7 @@ will need to switch to using `no_root_squash` in your NFS exports on the NFS ser
|
|||
This applies to operating systems using systemd (e.g. Ubuntu 16.04+, CentOS, etc.).
|
||||
|
||||
Since GitLab 11.2, the `gitlab-runsvdir` starts during the `multi-user.target`
|
||||
instead of `basic.target`. If you are having trouble starting this service
|
||||
instead of `basic.target`. If you are having trouble starting this service
|
||||
after upgrading GitLab, you may need to check that your system has properly
|
||||
booted all the required services for `multi-user.target` via the command:
|
||||
|
||||
|
|
|
|||
|
|
@ -56,7 +56,7 @@ In `files/gitlab-cookbooks/package/libraries/config/gitlab.rb` you will find the
|
|||
`attribute` methods.
|
||||
|
||||
If your service exists within the attributes for the GitLab cookbook, you should
|
||||
add it within the `attribute_block('gitlab')` block. Otherwise, if your service
|
||||
add it within the `attribute_block('gitlab')` block. Otherwise, if your service
|
||||
has its own cookbook, add it above.
|
||||
|
||||
Add your service as an attribute, using an underscore to separate words, **even if you
|
||||
|
|
|
|||
|
|
@ -17,7 +17,7 @@ repositories of the local mirror and upstream should be added to
|
|||
`/.custom_sources.yml`.
|
||||
|
||||
The local mirror should be created in the <https://dev.gitlab.org/omnibus-mirror>
|
||||
project by a member of the Distribution team. It should have the
|
||||
project by a member of the Distribution team. It should have the
|
||||
`omnibus-builder deploy key` enabled.
|
||||
|
||||
See other Software services in the directory for examples on how to include your
|
||||
|
|
|
|||
|
|
@ -33,10 +33,10 @@ With the desired package downloaded, use your systems package management tool to
|
|||
|
||||
Change `http://gitlab.example.com` to the URL at which you want to access your GitLab instance. Installation will automatically configure and start GitLab at that URL.
|
||||
|
||||
> **Note:** Enabling HTTPS will require [additional configuration](settings/nginx.html#enable-https) to specify the certificates.
|
||||
> **Note:** Enabling HTTPS will require [additional configuration](settings/nginx.md#enable-https) to specify the certificates.
|
||||
|
||||
## Browse to the hostname and login
|
||||
|
||||
On your first visit, you'll be redirected to a password reset screen. Provide the password for the initial administrator account and you will be redirected back to the login screen. Use the default account's username `root` to login.
|
||||
|
||||
See our [documentation for detailed instructions on installing and configuration](https://docs.gitlab.com/omnibus/README.html#installation-and-configuration-using-omnibus-package).
|
||||
See our [documentation for detailed instructions on installing and configuration](README.md#installation-and-configuration-using-omnibus-package).
|
||||
|
|
|
|||
|
|
@ -20,7 +20,7 @@ These defauts are noted in the package [defaults document](defaults.md).
|
|||
## Checking the versions of bundled software
|
||||
|
||||
Once the Omnibus GitLab package is installed, all versions of the bundled
|
||||
libraries are located in `/opt/gitlab/version-manifest.txt`.
|
||||
libraries are located in `/opt/gitlab/version-manifest.txt`.
|
||||
|
||||
If you don't have the package installed, you can always check the Omnibus GitLab
|
||||
[source repository], specifically the [config directory].
|
||||
|
|
|
|||
|
|
@ -32,7 +32,7 @@ sudo crontab -e -u root
|
|||
The cron table will appear in an editor.
|
||||
|
||||
Enter the command to create a compressed tar file containing the contents of
|
||||
`/etc/gitlab/`. For example, schedule the backup to run every morning after a
|
||||
`/etc/gitlab/`. For example, schedule the backup to run every morning after a
|
||||
weekday, Tuesday (day 2) through Saturday (day 6):
|
||||
|
||||
```
|
||||
|
|
|
|||
|
|
@ -649,7 +649,7 @@ details.
|
|||
GitLab 12.2 added support for [CSP and nonces with inline
|
||||
JavaScript](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/script-src).
|
||||
It is [not configured on by default
|
||||
yet](https://gitlab.com/gitlab-org/gitlab/issues/30720). An example
|
||||
yet](https://gitlab.com/gitlab-org/gitlab/issues/30720). An example
|
||||
configuration that will work for most installations of GitLab is below:
|
||||
|
||||
```ruby
|
||||
|
|
|
|||
|
|
@ -1,9 +1,9 @@
|
|||
# Setting custom environment variables
|
||||
|
||||
If necessary you can set custom environment variables to be used by Unicorn,
|
||||
Sidekiq, Rails and Rake via `/etc/gitlab/gitlab.rb`. This can be useful in
|
||||
Sidekiq, Rails and Rake via `/etc/gitlab/gitlab.rb`. This can be useful in
|
||||
situations where you need to use a proxy to access the internet and need to
|
||||
clone externally hosted repositories directly into GitLab. In
|
||||
clone externally hosted repositories directly into GitLab. In
|
||||
`/etc/gitlab/gitlab.rb` supply a `gitlab_rails['env']` with a hash value. For
|
||||
example:
|
||||
|
||||
|
|
|
|||
|
|
@ -327,7 +327,7 @@ nginx['listen_addresses'] = ["0.0.0.0", "[::]"] # listen on all IPv4 and IPv6 ad
|
|||
By default NGINX will listen on the port specified in `external_url` or
|
||||
implicitly use the right port (80 for HTTP, 443 for HTTPS). If you are running
|
||||
GitLab behind a reverse proxy, you may want to override the listen port to
|
||||
something else. For example, to use port 8081:
|
||||
something else. For example, to use port 8081:
|
||||
|
||||
```ruby
|
||||
nginx['listen_port'] = 8081
|
||||
|
|
@ -336,7 +336,7 @@ nginx['listen_port'] = 8081
|
|||
## Supporting proxied SSL
|
||||
|
||||
By default NGINX will auto-detect whether to use SSL if `external_url`
|
||||
contains `https://`. If you are running GitLab behind a reverse proxy, you
|
||||
contains `https://`. If you are running GitLab behind a reverse proxy, you
|
||||
may wish to terminate SSL at another proxy server or load balancer. To do this,
|
||||
be sure the `external_url` contains `https://` and apply the following
|
||||
configuration to `gitlab.rb`:
|
||||
|
|
@ -782,9 +782,9 @@ systems `sudo service nginx restart`).
|
|||
|
||||
Make sure you don't have the `proxy_set_header` configuration in
|
||||
`nginx['custom_gitlab_server_config']` settings and instead use the
|
||||
['proxy_set_headers'](https://docs.gitlab.com/omnibus/settings/nginx.html#supporting-proxied-ssl) configuration in your `gitlab.rb` file.
|
||||
['proxy_set_headers'](#supporting-proxied-ssl) configuration in your `gitlab.rb` file.
|
||||
|
||||
### javax.net.ssl.SSLHandshakeException: Received fatal alert: handshake_failure
|
||||
### `javax.net.ssl.SSLHandshakeException: Received fatal alert: handshake_failure`
|
||||
|
||||
Starting with GitLab 10, the Omnibus GitLab package no longer supports TLSv1 protocol by default.
|
||||
This can cause connection issues with some older Java based IDE clients when interacting with
|
||||
|
|
|
|||
|
|
@ -15,7 +15,7 @@ Administrators can enable secure http using any method supported by a GitLab ser
|
|||
|-|-|-|
|
||||
| Primary GitLab Instance Domain | [Yes](nginx.md#manually-configuring-https) | [Yes](#lets-encrypt-integration) |
|
||||
| Container Registry | [Yes](https://docs.gitlab.com/ee/administration/packages/container_registry.html#configure-container-registry-under-its-own-domain) | [Yes](#lets-encrypt-integration) |
|
||||
| Mattermost | [Yes](https://docs.gitlab.com/omnibus/gitlab-mattermost/README.html#running-gitlab-mattermost-with-https) | [Yes](#lets-encrypt-integration) |
|
||||
| Mattermost | [Yes](../gitlab-mattermost/README.md#running-gitlab-mattermost-with-https) | [Yes](#lets-encrypt-integration) |
|
||||
| GitLab Pages | [Yes](https://docs.gitlab.com/ee/administration/pages/#wildcard-domains-with-tls-support) | No |
|
||||
|
||||
### Let's Encrypt Integration
|
||||
|
|
|
|||
|
|
@ -284,7 +284,7 @@ you've completed these steps.
|
|||
|
||||
#### Using PostgreSQL HA
|
||||
|
||||
Pick a node to be the `Deploy Node`. It can be any node, but it must be the same
|
||||
Pick a node to be the `Deploy Node`. It can be any node, but it must be the same
|
||||
node throughout the process.
|
||||
|
||||
**Deploy node**
|
||||
|
|
|
|||
|
|
@ -32,8 +32,8 @@ This assumes that `gitlab-shell` is located in `/home/git`.
|
|||
## Upgrading from non-Omnibus PostgreSQL to an Omnibus installation in-place
|
||||
|
||||
It is also possible to upgrade a source GitLab installation to Omnibus GitLab
|
||||
in-place. Below we assume you are using PostgreSQL on Ubuntu, and that you
|
||||
have an Omnibus GitLab package matching your current GitLab version. We also
|
||||
in-place. Below we assume you are using PostgreSQL on Ubuntu, and that you
|
||||
have an Omnibus GitLab package matching your current GitLab version. We also
|
||||
assume that your source installation of GitLab uses all the default paths and
|
||||
users.
|
||||
|
||||
|
|
|
|||
|
|
@ -3,7 +3,7 @@
|
|||
From version 10.0 GitLab requires the version of PostgreSQL to be 9.6 or
|
||||
higher.
|
||||
|
||||
Check out [docs on upgrading packaged PostgreSQL server](https://docs.gitlab.com/omnibus/settings/database.html#upgrade-packaged-postgresql-server)
|
||||
Check out [docs on upgrading packaged PostgreSQL server](../settings/database.md#upgrade-packaged-postgresql-server)
|
||||
for details.
|
||||
|
||||
- For users running versions below 8.15 and using PostgreSQL bundled with
|
||||
|
|
|
|||
|
|
@ -45,14 +45,14 @@ been removed:
|
|||
|
||||
1. Mattermost related configurations - Support for most of the Mattermost
|
||||
related configuration have been removed, except for the essential ones that
|
||||
are needed for GitLab-Mattermost integration. [Check out the official documentation for details](https://docs.gitlab.com/omnibus/gitlab-mattermost/#upgrading-gitlab-mattermost-from-versions-prior-to-11-0)
|
||||
are needed for GitLab-Mattermost integration. [Check out the official documentation for details](../gitlab-mattermost/README.md#upgrading-gitlab-mattermost-from-versions-prior-to-110)
|
||||
|
||||
1. Legacy `git_data_dir` configuration, which was used to set location of where
|
||||
data was to be stored. It has been now replaced with `git_data_dirs`
|
||||
configuration. [Check out the official documentation for details](https://docs.gitlab.com/omnibus/settings/configuration.html#storing-git-data-in-an-alternative-directory)
|
||||
configuration. [Check out the official documentation for details](../settings/configuration.md#storing-git-data-in-an-alternative-directory)
|
||||
|
||||
1. Old format of `git_data_dirs` configuration has been replaced with a new
|
||||
format, allowing much more fine grain control. [Check out the official documentation for details](https://docs.gitlab.com/omnibus/settings/configuration.html#storing-git-data-in-an-alternative-directory)
|
||||
format, allowing much more fine grain control. [Check out the official documentation for details](../settings/configuration.md#storing-git-data-in-an-alternative-directory)
|
||||
|
||||
## Changes introduced in minor versions
|
||||
|
||||
|
|
@ -72,7 +72,7 @@ Rack Attack is disabled by default. To continue using Rack Attack, you must [ena
|
|||
|
||||
For users looking for preserving the Prometheus version 1 data, a command
|
||||
line tool is provided to upgrade their Prometheus service and migrate data to
|
||||
the format supported by new Prometheus version. This tool can be invoked
|
||||
the format supported by new Prometheus version. This tool can be invoked
|
||||
using the following command:
|
||||
|
||||
```bash
|
||||
|
|
@ -81,7 +81,7 @@ Rack Attack is disabled by default. To continue using Rack Attack, you must [ena
|
|||
|
||||
This tool will convert existing data to a format supported by the latest
|
||||
Prometheus version. Depending on the volume of data, this process can take
|
||||
hours. If users do not want to migrate the data, but start with a clean
|
||||
hours. If users do not want to migrate the data, but start with a clean
|
||||
database, they can pass `--skip-data-migration` flag to the above command.
|
||||
|
||||
NOTE: **Note**: Prometheus service will be stopped during the migration process.
|
||||
|
|
|
|||
|
|
@ -8,7 +8,7 @@ When upgrading to a new major version, remember to first [check for background m
|
|||
Prometheus 1.x was deprecated in GitLab 11.4, and
|
||||
Prometheus 2.8.1 was installed by default on new installations. Users updating
|
||||
from older versions of GitLab could manually upgrade Prometheus data using the
|
||||
[`gitlab-ctl prometheus-upgrade`](https://docs.gitlab.com/omnibus/update/gitlab_11_changes.html#114)
|
||||
[`gitlab-ctl prometheus-upgrade`](gitlab_11_changes.md#114)
|
||||
command provided. You can view current Prometheus version in use from the
|
||||
instances Prometheus `/status` page.
|
||||
|
||||
|
|
@ -16,7 +16,7 @@ With GitLab 12.0, support for Prometheus 1.x is completely removed, and as part
|
|||
of the upgrade process, Prometheus binaries will be updated to version 2.8.1.
|
||||
Existing data from Prometheus 1.x installation WILL NOT be migrated as part of
|
||||
this automatic upgrade, and users who wish to retain that data should
|
||||
[manually upgrade Prometheus version](https://docs.gitlab.com/omnibus/update/gitlab_11_changes.html#114)
|
||||
[manually upgrade Prometheus version](gitlab_11_changes.md#114)
|
||||
before upgrading to GitLab 12.0
|
||||
|
||||
For users who use `/etc/gitlab/skip-auto-reconfigure` file to skip automatic
|
||||
|
|
@ -110,7 +110,7 @@ ones at the earliest.
|
|||
The Redis version packaged with Omnibus GitLab has been updated to Redis 5.0.7.
|
||||
You will need to restart Redis after the upgrade so that the new version will be
|
||||
active. To restart Redis, run `sudo gitlab-ctl restart redis`. If your instance
|
||||
has Redis HA with Sentinel, follow the upgrade steps documented in [Updating GitLab installed with the Omnibus GitLab package](https://docs.gitlab.com/omnibus/update/README.html#using-redis-ha-using-sentinel)
|
||||
has Redis HA with Sentinel, follow the upgrade steps documented in [Updating GitLab installed with the Omnibus GitLab package](README.md#using-redis-ha-using-sentinel)
|
||||
to avoid downtime.
|
||||
|
||||
### 12.8
|
||||
|
|
|
|||
|
|
@ -135,6 +135,8 @@ docs-lint:
|
|||
before_script: []
|
||||
<<: *dedicated-runner
|
||||
script:
|
||||
# Lint prose
|
||||
- vale --minAlertLevel error doc
|
||||
# Lint Markdown
|
||||
- markdownlint --config .markdownlint.json 'doc/**/*.md'
|
||||
# Prepare docs for build
|
||||
|
|
|
|||
Loading…
Reference in New Issue