Appearance API
Introduced in GitLab 12.7.
The appearance API allows you to maintain the appearance of GitLab as if
you’re using the GitLab UI at /admin/appearance. The API requires
administrator privileges.
Get current appearance configuration
List the current appearance configuration of the GitLab instance.
GET /application/appearance
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/application/appearance"
Example response:
{
"title": "GitLab Test Instance",
"description": "gitlab-test.example.com",
"pwa_name": "GitLab PWA",
"pwa_short_name": "GitLab",
"pwa_description": "GitLab as PWA",
"pwa_icon": "/uploads/-/system/appearance/pwa_icon/1/pwa_logo.png",
"logo": "/uploads/-/system/appearance/logo/1/logo.png",
"header_logo": "/uploads/-/system/appearance/header_logo/1/header.png",
"favicon": "/uploads/-/system/appearance/favicon/1/favicon.png",
"new_project_guidelines": "Please read the FAQs for help.",
"profile_image_guidelines": "Custom profile image guidelines",
"header_message": "",
"footer_message": "",
"message_background_color": "#e75e40",
"message_font_color": "#ffffff",
"email_header_and_footer_enabled": false
}
Change appearance configuration
Use an API call to modify GitLab instance appearance configuration.
PUT /application/appearance
| Attribute | Type | Required | Description |
|---|---|---|---|
title | string | no | Instance title on the sign in / sign up page |
description | string | no | Markdown text shown on the sign in / sign up page |
pwa_name | string | no | Full name of the Progressive Web App. Used for the attribute name in manifest.json. Introduced in GitLab 15.8. |
pwa_short_name | string | no | Short name for Progressive Web App. Introduced in GitLab 15.8. |
pwa_description | string | no | An explanation of what the Progressive Web App does. Used for the attribute description in manifest.json. Introduced in GitLab 15.8. |
pwa_icon | mixed | no | Icon used for Progressive Web App. See Change logo. Introduced in GitLab 15.8. |
logo | mixed | no | Instance image used on the sign in / sign up page. See Change logo |
header_logo | mixed | no | Instance image used for the main navigation bar |
favicon | mixed | no | Instance favicon in .ico or .png format |
new_project_guidelines | string | no | Markdown text shown on the new project page |
profile_image_guidelines | string | no | Markdown text shown on the profile page below Public Avatar |
header_message | string | no | Message in the system header bar |
footer_message | string | no | Message in the system footer bar |
message_background_color | string | no | Background color for the system header / footer bar |
message_font_color | string | no | Font color for the system header / footer bar |
email_header_and_footer_enabled | boolean | no | Add header and footer to all outgoing emails if enabled |
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/application/appearance?email_header_and_footer_enabled=true&header_message=test"
Example response:
{
"title": "GitLab Test Instance",
"description": "gitlab-test.example.com",
"pwa_name": "GitLab PWA",
"pwa_short_name": "GitLab",
"pwa_description": "GitLab as PWA",
"pwa_icon": "/uploads/-/system/appearance/pwa_icon/1/pwa_logo.png",
"logo": "/uploads/-/system/appearance/logo/1/logo.png",
"header_logo": "/uploads/-/system/appearance/header_logo/1/header.png",
"favicon": "/uploads/-/system/appearance/favicon/1/favicon.png",
"new_project_guidelines": "Please read the FAQs for help.",
"profile_image_guidelines": "Custom profile image guidelines",
"header_message": "test",
"footer_message": "",
"message_background_color": "#e75e40",
"message_font_color": "#ffffff",
"email_header_and_footer_enabled": true
}
Change logo
Upload a logo to your GitLab instance.
To upload an avatar from your file system, use the --form argument. This causes
cURL to post data using the header Content-Type: multipart/form-data. The
file= parameter must point to an image file on your file system and be
preceded by @.
PUT /application/appearance
| Attribute | Type | Required | Description |
|---|---|---|---|
logo | mixed | Yes | File to upload |
pwa_icon | mixed | Yes | File to upload. Introduced in GitLab 15.8. |
Example request:
curl --location --request PUT "https://gitlab.example.com/api/v4/application/appearance?data=image/png" \
--header "Content-Type: multipart/form-data" \
--header "PRIVATE-TOKEN: <your_access_token>" \
--form "logo=@/path/to/logo.png"
Returned object:
{
"logo":"/uploads/-/system/appearance/logo/1/logo.png"
}