Skip to content

G
gitlab-ce
Commit c356c90e authored by Marcel Amirault's avatar Marcel Amirault Committed by Russell Dickenson
Browse files
Options

First phase of admin_area appearance refactor 

Move most information regarding the appearance section
to /user/admin_area, and redirect from /customization.
Updates screenshots, information, process, etc.
parent 57d11caa
Hide whitespace changes
Inline Side-by-side
Showing with 283 additions and 307 deletions
doc/administration/libravatar.md 0 → 100644
View file @ c356c90e
---
type: howto
---
# Using the Libravatar service with GitLab
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 the [`gitlab.yml` gravatar section](https://gitlab.com/gitlab-org/gitlab/blob/672bd3902d86b78d730cea809fce312ec49d39d7/config/gitlab.yml.example#L122), set
the configuration options as follows:
### For HTTP
```yml
gravatar:
enabled: true
# gravatar URLs: possible placeholders: %{hash} %{size} %{email} %{username}
plain_url: "http://cdn.libravatar.org/avatar/%{hash}?s=%{size}&d=identicon"
```
### For HTTPS
```yml
gravatar:
enabled: true
# gravatar URLs: possible placeholders: %{hash} %{size} %{email} %{username}
ssl_url: "https://seccdn.libravatar.org/avatar/%{hash}?s=%{size}&d=identicon"
```
### 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 you must provide the same
placeholders so GitLab can parse the URL correctly.
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`
### Omnibus GitLab example
In `/etc/gitlab/gitlab.rb`:
#### 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
```ruby
gitlab_rails['gravatar_enabled'] = true
gitlab_rails['gravatar_ssl_url'] = "https://seccdn.libravatar.org/avatar/%{hash}?s=%{size}&d=identicon"
```
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 user email addresses that are not found on the Libravatar
service.
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 for Microsoft 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. -->
doc/customization/branded_login_page.md
View file @ c356c90e
---
type: howto
redirect_to: '../user/admin_area/appearance.md#sign-in--sign-up-pages'
---
# Changing the logo and description on the login page
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)
To customize the login 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.
![appearance](branded_login_page/appearance.png)
1. Save your changes.
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. -->
This document was moved to [another location](../user/admin_area/appearance.md#sign-in--sign-up-pages).
doc/customization/branded_page_and_email_header.md
View file @ c356c90e
---
type: howto
redirect_to: '../user/admin_area/appearance.md#navigation-bar'
---
# Changing the navigation bar and email header logo
You can customize the logo that appears in email headers and in the navigation
bar on pages that are displayed by your GitLab server.
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.
![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 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. -->
This document was moved to [another location](../user/admin_area/appearance.md#navigation-bar).
doc/customization/favicon.md
View file @ c356c90e
---
type: howto
redirect_to: '../user/admin_area/appearance.md#favicon'
---
# Changing the favicon
> [Introduced][ce-14497] in GitLab 11.0.
[ce-14497]: https://gitlab.com/gitlab-org/gitlab-foss/merge_requests/14497
You can customize the favicon (the icon displayed in your web browser's
address bar and web page tabs) for your GitLab server.
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)
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. -->
This document was moved to [another location](../user/admin_area/appearance.md#favicon).
doc/customization/help_message.md
View file @ c356c90e
---
type: howto
redirect_to: '../user/admin_area/settings/help_page.md'
---
# Customizing the 'Help' and login page messages
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. 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)
1. Save your changes.
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. -->
This document was moved to [another location](../user/admin_area/settings/help_page.md).
doc/customization/index.md
View file @ c356c90e
---
type: index
description: Learn how to customize GitLab's appearance for self-managed installations.
redirect_to: '../user/admin_area/appearance.md'
---
# Customizing GitLab's appearance **(CORE ONLY)**
For GitLab self-managed instances, you can customize the page logo,
email headers, favicon, and several other aspects of GitLab's appearance.
The following pages explain how to customize the appearance of your instance:
- [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)
This document was moved to [another location](../user/admin_area/appearance.md).
doc/customization/libravatar.md
View file @ c356c90e
---
type: howto
redirect_to: '../administration/libravatar.md'
---
# Using the Libravatar service with GitLab
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 the [`gitlab.yml` gravatar section](https://gitlab.com/gitlab-org/gitlab/blob/672bd3902d86b78d730cea809fce312ec49d39d7/config/gitlab.yml.example#L122), set
the configuration options as follows:
### For HTTP
```yml
gravatar:
enabled: true
# gravatar URLs: possible placeholders: %{hash} %{size} %{email} %{username}
plain_url: "http://cdn.libravatar.org/avatar/%{hash}?s=%{size}&d=identicon"
```
### For HTTPS
```yml
gravatar:
enabled: true
# gravatar URLs: possible placeholders: %{hash} %{size} %{email} %{username}
ssl_url: "https://seccdn.libravatar.org/avatar/%{hash}?s=%{size}&d=identicon"
```
### 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 you must provide the same
placeholders so GitLab can parse the URL correctly.
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`
### Omnibus GitLab example
In `/etc/gitlab/gitlab.rb`:
#### 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
```ruby
gitlab_rails['gravatar_enabled'] = true
gitlab_rails['gravatar_ssl_url'] = "https://seccdn.libravatar.org/avatar/%{hash}?s=%{size}&d=identicon"
```
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 user email addresses that are not found on the Libravatar
service.
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 for Microsoft 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. -->
This document was moved to [another location](../administration/libravatar.md).
doc/customization/new_project_page.md
View file @ c356c90e
---
type: howto
redirect_to: '../user/admin_area/appearance.md#new-project-pages'
---
# Customizing the 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:
![default_new_project_page](new_project_page/default_new_project_page.png)
To customize the information in the sidebar:
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:
![appearance_settings](new_project_page/appearance_settings.png)
1. Save the page.
Your new project page will show the customized guidelines in the sidebar, below
the general information:
![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. -->
This document was moved to [another location](../user/admin_area/appearance.md#new-project-pages).
doc/customization/system_header_and_footer_messages.md
View file @ c356c90e
# Adding a system message to every page
---
redirect_to: '../user/admin_area/appearance.md#system-header-and-footer-messages'
---
> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/5023) in [GitLab Premium](https://about.gitlab.com/pricing/) 10.7.
> [Added](https://gitlab.com/gitlab-org/gitlab-foss/issues/55057) to [GitLab Core](https://about.gitlab.com/pricing/) in 11.9.
Navigate to the **Admin** area and go to the **Appearance** page.
Under **System header and footer** insert your header message and/or footer message.
Both background and font color of the header and footer are customizable.
You can also apply the header and footer messages to GitLab emails,
by checking the **Enable header and footer in emails** checkbox.
Note that color settings will only be applied within the app interface and not to emails
![appearance](system_header_and_footer_messages/appearance.png)
After saving, all pages within GitLab will contain the custom system header and/or footer messages:
![custom_header_footer](system_header_and_footer_messages/custom_header_footer.png)
The GitLab sign in page will also show the header and the footer messages:
![sign_up_custom_header_and_footer](system_header_and_footer_messages/sign_up_custom_header_and_footer.png)
This document was moved to [another location](../user/admin_area/appearance.md#system-header-and-footer-messages).
doc/user/admin_area/appearance.md 0 → 100644
View file @ c356c90e
---
type: howto
disqus_identifier: 'https://docs.gitlab.com/ee/customization/branded_login_page.html'
---
# GitLab Appearance **(CORE ONLY)**
There are several options for customizing the appearance of a self hosted instance
of GitLab. These settings are accessed from the **Admin Area** in the **Appearance**
section.
## Navigation bar
By default, the navigation bar has the GitLab logo, but this can be customized with
any image desired. It is optimized for images 28px high (any width), but any image can be
used (less than 1MB) and it will automatically be resized.
![navbar header logo screenshot](img/appearance_header_logo_v12_3.png)
Once you select and upload an image, click **Update appearance settings** at the bottom
of the page to activate it in the GitLab instance.
NOTE: **Note:**
GitLab pipeline emails will also display the custom logo.
## Favicon
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/merge_requests/14497) in GitLab 11.0.
By default, the favicon (used by the browser as the tab icon, as well as the CI status icon)
uses the GitLab logo, but this can be customized with any icon desired. It must be a
32x32 `.png` or `.ico` image.
![favicon screenshot](img/appearance_favicon_v12_3.png)
After you select and upload an icon, click **Update appearance settings** at the bottom
of the page to activate it in the GitLab instance.
## System header and footer messages
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/5023) in [GitLab Premium](https://about.gitlab.com/pricing/) 10.7.
> - [Added](https://gitlab.com/gitlab-org/gitlab-foss/issues/55057) to [GitLab Core](https://about.gitlab.com/pricing/) in 11.9.
You can add a small header message, a small footer message, or both, to the interface
of your GitLab instance. These messages will appear on all projects and pages of the
instance, including the sign in / sign up page. The default color is white text on
an orange background, but this can be customized by clicking on **Customize colors**.
Limited [markdown](../markdown.md) is supported, such as bold, italics, and links, for
example. Other markdown features, including lists, images and quotes, are not supported,
as the header and footer messages can only be a single line.
![header and footer screenshot](img/appearance_header_footer_v12_3.png)
If desired, you can select **Enable header and footer in emails** to have the text of
the header and footer added to all emails sent by the GitLab instance.
After you add a message, click **Update appearance settings** at the bottom of the page
to activate it in the GitLab instance.
## Sign in / Sign up pages
You can replace the default message on the sign in / sign up page with your own message
and logo. You can make full use of [markdown](../markdown.md) in the description:
![sign in message screenshot](img/appearance_sign_in_v12_3.png)
The optimal size for the logo is 640x360px, but any image can be used (below 1MB)
and it will be resized automatically. The logo image will appear between the title and
the description, on the left of the sign-up page.
![sign in message preview screenshot](img/appearance_sign_in_preview_v12_3.png)
After you add a message, click **Update appearance settings** at the bottom of the page
to activate it in the GitLab instance. You can also click on the **Sign-in page** button,
to review the saved appearance settings:
NOTE: **Note:**
You can add also add a [customized help message](settings/help_page.md) below the sign in message.
## New project pages
You can add a new project guidelines message to the **New project page** within GitLab.
You can make full use of [markdown](../markdown.md) in the description:
![new project message screenshot](img/appearance_new_project_v12_3.png)
The message will be displayed below the **New Project** message, on the left side
of the **New project page**.
After you add a message, click **Update appearance settings** at the bottom of the page
to activate it in the GitLab instance. You can also click on the **New project page**
button, which will bring you to the new project page so you can review the change.
![new project message preview screenshot](img/appearance_new_project_preview_v12_3.png)
## Libravatar
[Libravatar](https://www.libravatar.org) is supported by GitLab for avatar images, but you must
[manually enable Libravatar support on the GitLab instance](../../administration/libravatar.md)
in order to use the service.
<!-- ## 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. -->
doc/user/admin_area/index.md
View file @ c356c90e
......@@ -32,7 +32,7 @@ The Admin Area is made up of the following sections:
| Deploy Keys | Create instance-wide [SSH deploy keys](../../ssh/README.md#deploy-keys). |
| Service Templates | Create [service templates](../project/integrations/services_templates.md) for projects. |
| Labels | Create and maintain [labels](labels.md) for your GitLab instance. |
| Appearance | Customize [GitLab's appearance](../../customization/index.md). |
| Appearance | Customize [GitLab's appearance](appearance.md). |
| Settings | Modify the [settings](settings/index.md) for your GitLab instance. |
## Admin Dashboard
......
doc/user/admin_area/settings/help_page.md 0 → 100644
View file @ c356c90e
---
type: howto
---
# Customizing the 'Help' and login page messages
In large organizations, it is useful to have information about who to contact or where
to go for help. You can customize and display this information on the GitLab server's
`/help` page and on the GitLab login page.
## Adding a help message to the help page
You can add a help message, which will be shown on the GitLab `/help` page (e.g.,
<https://gitlab.com/help>) in a new section at the top of the `/help` page:
1. Navigate to **Admin area > Settings > Preferences**, then expand **Help page**.
1. Under **Help page text**, fill in the information you wish to display on `/help`.
![help page help message](img/help_page_help_page_text_v12_3.png)
1. Save your changes. You can now see the message on `/help`.
![help message on help page example](img/help_page_help_page_text_ex_v12_3.png)
## Adding a help message to the login page **(STARTER)**
You can add a help message, which will be shown on the GitLab login page in a new section
titled `Need Help?`, located below the login page message:
1. Navigate to **Admin area > Settings > Preferences**, then expand **Help page**.
1. Under **Help text**, fill in the information you wish to display on the login page.
![help message on login page](img/help_page_help_text_v12_3.png)
1. Save your changes.
![help message on login page example](img/help_page_help_text_ex_v12_3.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. -->
doc/user/admin_area/settings/index.md
View file @ c356c90e
......@@ -21,6 +21,7 @@ include:
- [User and IP rate limits](user_and_ip_rate_limits.md)
- [Custom templates repository](instance_template_repository.md) **(PREMIUM)**
- [Protected paths](protected_paths.md) **(CORE ONLY)**
- [Help messages for the `/help` page and the login page](help_page.md)
NOTE: **Note:**
You can change the [first day of the week](../../profile/preferences.md) for the entire GitLab instance
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7