summaryrefslogtreecommitdiff
path: root/doc/api/appearance.md
blob: d03fc94cfcf62d122634258dac4ffe02cb3ad902 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
---
stage: Manage
group: Access
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
---

# Appearance API **(CORE ONLY)**

> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/16647) 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.

```plaintext
GET /application/appearance
```

```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/application/appearance"
```

Example response:

```json
{
  "title": "GitLab Test Instance",
  "description": "gitlab-test.example.com",
  "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.

```plaintext
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
| `logo`                            | mixed   | no       | Instance image used on the sign in / sign up page. See [Change logo](#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

```shell
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:

```json
{
  "title": "GitLab Test Instance",
  "description": "gitlab-test.example.com",
  "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 `@`.

```plaintext
PUT /application/appearance
```

| Attribute | Type   | Required | Description    |
| --------- | ------ | -------- | -------------- |
| `logo`    | string | Yes      | File to upload |

Example request:

```shell
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:

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