kotovalexarian-likes-gitlab/gitlab-org--gitlab-foss
1
0
Fork 0
Code Releases Activity

Merge branch 'docs-ssot-customization' into 'master'

Browse source 
SSoT for customization docs

Closes #64588

See merge request gitlab-org/gitlab-ce!31308
This commit is contained in:
Achilleas Pipinellis 2019-08-06 11:10:47 +00:00
commit f6a201a838
7 changed files with 192 additions and 66 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

35
doc/customization/branded_login_page.md
View file

@ -1,19 +1,38 @@
# Changing the appearance of the login page
---
type: howto
---
GitLab offers a way to put your company's identity on the login page of your GitLab server and make it a branded login page.
# Changing the logo and description on the login page
By default, the page shows the GitLab logo and description.
You can customize the login page of your GitLab server to show the logo and
description of your organization.
By default, the page shows the GitLab logo and description:
![default_login_page](branded_login_page/default_login_page.png)
## Changing the appearance of the login page
To customize the login page:
Navigate to the **Admin** area and go to the **Appearance** page.
1. Navigate to the **Admin** area and go to the **Appearance** page.
1. Fill in your desired Title and Description. You can also choose an image file
of the logo for your organization.
Fill in the required details like Title, Description and upload the company logo.
![appearance](branded_login_page/appearance.png)
![appearance](branded_login_page/appearance.png)
1. Save your changes.
After saving the page, your GitLab login page will have the details you filled in:
Your GitLab login page will display the details you provided:
![company_login_page](branded_login_page/custom_sign_in.png)
<!-- ## Troubleshooting
Include any troubleshooting steps that you can foresee. If you know beforehand what issues
one might have when setting this up, or when something is changed, or on upgrading, it's
important to describe those, too. Think of things that may go wrong and include them here.
This is important to minimize requests for support, and to avoid doc comments with
questions that you know someone might ask.
Each scenario can be a third-level heading, e.g. `### Getting error message X`.
If you have none to add when creating a doc, leave this section in place
but commented out to help encourage others to add to it in the future. -->

34
doc/customization/branded_page_and_email_header.md
View file

@ -1,15 +1,37 @@
# Changing the logo on the overall page and email header
---
type: howto
---
Navigate to the **Admin** area and go to the **Appearance** page.
# Changing the navigation bar and email header logo
Upload the custom logo (**Header logo**) in the section **Navigation bar**.
You can customize the logo that appears in email headers and in the navigation
bar on pages that are displayed by your GitLab server.
![appearance](branded_page_and_email_header/appearance.png)
1. Navigate to the **Admin** area and go to the **Appearance** page, then locate
the **Navigation bar** section.
1. For the **Header Logo**, choose an image file of the logo for your
organization.
After saving the page, your GitLab navigation bar will contain the custom logo:
![appearance](branded_page_and_email_header/appearance.png)
1. Save your changes.
Your GitLab navigation bar will display the custom logo:
![custom_brand_header](branded_page_and_email_header/custom_brand_header.png)
The GitLab pipeline emails will also have the custom logo:
The GitLab pipeline emails will also display the custom logo:
![custom_email_header](branded_page_and_email_header/custom_email_header.png)
<!-- ## Troubleshooting
Include any troubleshooting steps that you can foresee. If you know beforehand what issues
one might have when setting this up, or when something is changed, or on upgrading, it's
important to describe those, too. Think of things that may go wrong and include them here.
This is important to minimize requests for support, and to avoid doc comments with
questions that you know someone might ask.
Each scenario can be a third-level heading, e.g. `### Getting error message X`.
If you have none to add when creating a doc, leave this section in place
but commented out to help encourage others to add to it in the future. -->

31
doc/customization/favicon.md
View file

@ -1,16 +1,37 @@
---
type: howto
---
# Changing the favicon
> [Introduced][ce-14497] in GitLab 11.0.
[ce-14497]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/14497
Navigate to the **Admin** area and go to the **Appearance** page.
You can customize the favicon (the icon displayed in your web browser's
address bar and web page tabs) for your GitLab server.
Upload the custom favicon (**Favicon**) in the section **Favicon**.
1. Navigate to the **Admin** area and go to the **Appearance** page, then
locate the **Favicon** section.
1. Upload an image file of your favicon.
![appearance](favicon/appearance.png)
![appearance](favicon/appearance.png)
After saving the page, the new favicon will be shown in the browser. The main
favicon as well as the CI status icons will show the custom icon:
1. Save your changes.
Your new favicon will display in the browser. The main favicon and the CI
status icons will show the custom icon:
![custom_favicon](favicon/custom_favicon.png)
<!-- ## Troubleshooting
Include any troubleshooting steps that you can foresee. If you know beforehand what issues
one might have when setting this up, or when something is changed, or on upgrading, it's
important to describe those, too. Think of things that may go wrong and include them here.
This is important to minimize requests for support, and to avoid doc comments with
questions that you know someone might ask.
Each scenario can be a third-level heading, e.g. `### Getting error message X`.
If you have none to add when creating a doc, leave this section in place
but commented out to help encourage others to add to it in the future. -->

37
doc/customization/help_message.md
View file

@ -1,13 +1,36 @@
# GitLab Help custom text
---
type: howto
---
In larger organizations it is useful to have information about who has the responsibility of maintaining the company GitLab server.
# Customizing the 'Help' and login page messages
1. Navigate to the admin area, click on **Preferences** and expand **Help page**.
In large organizations, it is useful to have information about who maintains
the company GitLab server. You can customize and display this information on
the GitLab login page and on the GitLab server's `/help` page.
1. Under **Help text** fill in the required information about the person(s) administering GitLab or any other information relevant to your needs.
1. Navigate to the **Admin** area, then click on **Preferences** and expand
**Help page**.
1. Under **Help page text**, fill in the required information about the
person(s) administering GitLab. This text can also contain any other
information that you wish to display to users.
![help message](help_message/help_text.png)
![help message](help_message/help_text.png)
1. After saving the page this information will be shown on the GitLab login page and on the GitLab `/help` page (e.g., <https://gitlab.com/help>).
1. Save your changes.
![help text on help page](help_message/help_text_on_help_page.png)
The information you entered will be shown on the GitLab login page and on the
GitLab `/help` page (e.g., <https://gitlab.com/help>).
![help text on help page](help_message/help_text_on_help_page.png)
<!-- ## Troubleshooting
Include any troubleshooting steps that you can foresee. If you know beforehand what issues
one might have when setting this up, or when something is changed, or on upgrading, it's
important to describe those, too. Think of things that may go wrong and include them here.
This is important to minimize requests for support, and to avoid doc comments with
questions that you know someone might ask.
Each scenario can be a third-level heading, e.g. `### Getting error message X`.
If you have none to add when creating a doc, leave this section in place
but commented out to help encourage others to add to it in the future. -->

20
doc/customization/index.md
View file

@ -1,18 +1,18 @@
---
type: index
description: Learn how to customize GitLab's appearance for self-managed installations.
---
# Customizing GitLab's appearance **(CORE ONLY)**
For GitLab self-managed instances, it's possible to customize
a few pages.
For GitLab self-managed instances, you can customize the page logo,
email headers, favicon, and several other aspects of GitLab's appearance.
Read through the following documents to adjust GitLab's
look and feel to meet your needs:
The following pages explain how to customize the appearance of your instance:
- [Custom login page](branded_login_page.md)
- [Custom header and email logo](branded_page_and_email_header.md)
- [Custom favicon](favicon.md)
- [Libravatar](libravatar.md)
- [New project page](new_project_page.md)
- [Custom `/help` message](help_message.md)
- [Changing the logo and description on the login page](branded_login_page.md)
- [Changing the navigation bar and email header logo](branded_page_and_email_header.md)
- [Changing the favicon](favicon.md)
- [Customizing the new project page](new_project_page.md)
- [Customizing the `/help` and login page messages](help_message.md)
- [Using the Libravatar service with GitLab](libravatar.md)

65
doc/customization/libravatar.md
View file

@ -1,14 +1,20 @@
# Use Libravatar service with GitLab
---
type: howto
---
GitLab by default supports [Gravatar](https://gravatar.com) avatar service.
Libravatar is a service which delivers your avatar (profile picture) to other websites and their API is
[heavily based on gravatar](https://wiki.libravatar.org/api/).
# Using the Libravatar service with GitLab
This means that it is not complicated to switch to Libravatar avatar service or even self hosted Libravatar server.
GitLab by default supports the [Gravatar](https://gravatar.com) avatar service.
Libravatar is another service that delivers your avatar (profile picture) to
other websites. The Libravatar API is
[heavily based on gravatar](https://wiki.libravatar.org/api/), so you can
easily switch to the Libravatar avatar service or even a self-hosted Libravatar
server.
## Configuration
In [gitlab.yml gravatar section](https://gitlab.com/gitlab-org/gitlab-ce/blob/672bd3902d86b78d730cea809fce312ec49d39d7/config/gitlab.yml.example#L122) set
In the [gitlab.yml gravatar section](https://gitlab.com/gitlab-org/gitlab-ce/blob/672bd3902d86b78d730cea809fce312ec49d39d7/config/gitlab.yml.example#L122), set
the configuration options as follows:
### For HTTP
@ -29,12 +35,14 @@ the configuration options as follows:
ssl_url: "https://seccdn.libravatar.org/avatar/%{hash}?s=%{size}&d=identicon"
```
### Self-hosted
### Self-hosted Libravatar server
If you are [running your own libravatar service](https://wiki.libravatar.org/running_your_own/) the URL will be different in the configuration
but the important part is to provide the same placeholders so GitLab can parse the URL correctly.
If you are [running your own libravatar service](https://wiki.libravatar.org/running_your_own/),
the URL will be different in the configuration, but you must provide the same
placeholders so GitLab can parse the URL correctly.
For example, you host a service on `http://libravatar.example.com` the `plain_url` you need to supply in `gitlab.yml` is
For example, you host a service on `http://libravatar.example.com` and the
`plain_url` you need to supply in `gitlab.yml` is
`http://libravatar.example.com/avatar/%{hash}?s=%{size}&d=identicon`
@ -42,37 +50,52 @@ For example, you host a service on `http://libravatar.example.com` the `plain_ur
In `/etc/gitlab/gitlab.rb`:
#### For http
#### For HTTP
```ruby
gitlab_rails['gravatar_enabled'] = true
gitlab_rails['gravatar_plain_url'] = "http://cdn.libravatar.org/avatar/%{hash}?s=%{size}&d=identicon"
```
#### For https
#### For HTTPS
```ruby
gitlab_rails['gravatar_enabled'] = true
gitlab_rails['gravatar_ssl_url'] = "https://seccdn.libravatar.org/avatar/%{hash}?s=%{size}&d=identicon"
```
Run `sudo gitlab-ctl reconfigure` for changes to take effect.
Then run `sudo gitlab-ctl reconfigure` for the changes to take effect.
## Default URL for missing images
[Libravatar supports different sets](https://wiki.libravatar.org/api/) of `missing images` for emails not found on the Libravatar service.
[Libravatar supports different sets](https://wiki.libravatar.org/api/) of
missing images for user email addresses that are not found on the Libravatar
service.
In order to use a different set other than `identicon`, replace `&d=identicon` portion of the URL with another supported set.
For example, you can use `retro` set in which case the URL would look like: `plain_url: "http://cdn.libravatar.org/avatar/%{hash}?s=%{size}&d=retro"`
In order to use a set other than `identicon`, replace the `&d=identicon`
portion of the URL with another supported set.
For example, you can use the `retro` set, in which case the URL would look like:
`plain_url: "http://cdn.libravatar.org/avatar/%{hash}?s=%{size}&d=retro"`
## Usage examples
## Usage examples for Microsoft Office 365
### For Microsoft Office 365
If your users are Office 365-users, the "GetPersonaPhoto" service can be used. Note that this service requires login, so this use case is
most useful in a corporate installation, where all users have access to Office 365.
If your users are Office 365 users, the `GetPersonaPhoto` service can be used.
Note that this service requires a login, so this use case is most useful in a
corporate installation where all users have access to Office 365.
```ruby
gitlab_rails['gravatar_plain_url'] = 'http://outlook.office365.com/owa/service.svc/s/GetPersonaPhoto?email=%{email}&size=HR120x120'
gitlab_rails['gravatar_ssl_url'] = 'https://outlook.office365.com/owa/service.svc/s/GetPersonaPhoto?email=%{email}&size=HR120x120'
```
<!-- ## Troubleshooting
Include any troubleshooting steps that you can foresee. If you know beforehand what issues
one might have when setting this up, or when something is changed, or on upgrading, it's
important to describe those, too. Think of things that may go wrong and include them here.
This is important to minimize requests for support, and to avoid doc comments with
questions that you know someone might ask.
Each scenario can be a third-level heading, e.g. `### Getting error message X`.
If you have none to add when creating a doc, leave this section in place
but commented out to help encourage others to add to it in the future. -->

36
doc/customization/new_project_page.md
View file

@ -1,20 +1,38 @@
---
type: howto
---
# Customizing the new project page
It is possible to add a markdown-formatted message to your GitLab
new project page.
You can add a markdown-formatted message to your GitLab new project page.
By default, the new project page shows a sidebar with general information:
![](new_project_page/default_new_project_page.png)
![default_new_project_page](new_project_page/default_new_project_page.png)
## Changing the appearance of the new project page
To customize the information in the sidebar:
Navigate to the **Admin** area and go to the **Appearance** page.
1. Navigate to the **Admin** area and go to the **Appearance** page, then
locate the **New project pages** section.
1. Fill in your new project project guidelines:
Fill in your project guidelines:
![appearance_settings](new_project_page/appearance_settings.png)
![](new_project_page/appearance_settings.png)
1. Save the page.
After saving the page, your new project page will show the guidelines in the sidebar, below the general information:
Your new project page will show the customized guidelines in the sidebar, below
the general information:
![](new_project_page/custom_new_project_page.png)
![custom_new_project_page](new_project_page/custom_new_project_page.png)
<!-- ## Troubleshooting
Include any troubleshooting steps that you can foresee. If you know beforehand what issues
one might have when setting this up, or when something is changed, or on upgrading, it's
important to describe those, too. Think of things that may go wrong and include them here.
This is important to minimize requests for support, and to avoid doc comments with
questions that you know someone might ask.
Each scenario can be a third-level heading, e.g. `### Getting error message X`.
If you have none to add when creating a doc, leave this section in place
but commented out to help encourage others to add to it in the future. -->