Application appearance API

  • Tier: Free, Premium, Ultimate
  • Offering: GitLab Self-Managed, GitLab Dedicated

Use this API to control the appearance of your GitLab instance. For more information, see GitLab Appearance.

Prerequisites:

  • You must have administrator access to the instance.

Get details on current application appearance

Gets details on the current appearance configuration for this GitLab instance.

GET /application/appearance

Example request:

curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "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
}

Update application appearance

Updates the current appearance configuration for this GitLab instance.

PUT /application/appearance
AttributeTypeRequiredDescription
titlestringnoInstance title on the sign in / sign up page
descriptionstringnoMarkdown text shown on the sign in / sign up page
pwa_namestringnoFull name of the Progressive Web App. Used for the attribute name in manifest.json. Introduced in GitLab 15.8.
pwa_short_namestringnoShort name for Progressive Web App. Introduced in GitLab 15.8.
pwa_descriptionstringnoAn explanation of what the Progressive Web App does. Used for the attribute description in manifest.json. Introduced in GitLab 15.8.
pwa_iconmixednoIcon used for Progressive Web App. See Update application logo. Introduced in GitLab 15.8.
logomixednoInstance image used on the sign in / sign up page. See Update application logo
header_logomixednoInstance image used for the main navigation bar
faviconmixednoInstance favicon in .ico or .png format
member_guidelinesstringnoMarkdown text shown on the group or project member page for users with permission to change members
new_project_guidelinesstringnoMarkdown text shown on the new project page
profile_image_guidelinesstringnoMarkdown text shown on the profile page below Public Avatar
header_messagestringnoMessage in the system header bar
footer_messagestringnoMessage in the system footer bar
message_background_colorstringnoBackground color for the system header / footer bar
message_font_colorstringnoFont color for the system header / footer bar
email_header_and_footer_enabledbooleannoAdd header and footer to all outgoing emails if enabled

Example request:

curl --request PUT \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "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
}

Updates the current logo for this GitLab instance with an included image file.

To upload an avatar from your local file system, use the --form argument to include the file. 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
AttributeTypeRequiredDescription
logomixedYesImage used as a logo.
pwa_iconmixedYesImage used for the Progressive Web App. Introduced in GitLab 15.8.

Example request:

curl --location --request PUT \
  --url "https://gitlab.example.com/api/v4/application/appearance?data=image/png" \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --header "Content-Type: multipart/form-data" \
  --form "logo=@/path/to/logo.png"

Example response:

{
  "logo":"/uploads/-/system/appearance/logo/1/logo.png"
}