Appearance API
- Tier: Free, Premium, Ultimate
- Offering: Self-managed, GitLab Dedicated
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
Example request:
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",
"member_guidelines": "Custom member guidelines",
"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 |
member_guidelines |
string | no | Markdown text shown on the group or project member page for users with permission to change members |
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 |
Example request:
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",
"member_guidelines": "Custom member guidelines",
"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"
Example response:
{
"logo":"/uploads/-/system/appearance/logo/1/logo.png"
}
Docs
Edit this page to fix an error or add an improvement in a merge request.
Create an issue to suggest an improvement to this page.
Product
Create an issue if there's something you don't like about this feature.
Propose functionality by submitting a feature request.
Feature availability and product trials
View pricing to see all GitLab tiers and features, or to upgrade.
Try GitLab for free with access to all features for 30 days.
Get help
If you didn't find what you were looking for, search the docs.
If you want help with something specific and could use community support, post on the GitLab forum.
For problems setting up or using this feature (depending on your GitLab subscription).
Request support