How to Customize the Argo CD UI: CSS Themes, Banners, and Branding Options

You customize the Argo CD UI by editing the argocd-cm ConfigMap to inject custom stylesheets, display global announcement banners, or modify SSO login button text, with changes automatically loaded by the UI server at runtime.

The argoproj/argo-cd repository provides a lightweight but powerful mechanism to tailor the web interface without rebuilding the application from source. By modifying specific keys in the argocd-cm ConfigMap, platform operators can override default styles, add informational banners, and relabel authentication buttons. These settings are defined in the ArgoCDSettings struct within util/settings/settings.go and injected into the React frontend by the server logic in ui/embed.go.

Customization Options Overview

Argo CD exposes four primary UI customization vectors through ConfigMap data keys. Each option targets a specific visual element and requires no downtime to deploy.

Custom Stylesheets (ui.cssurl)

The ui.cssurl key accepts either an external HTTPS URL or a local filesystem path pointing to a CSS file. The UI server injects this stylesheet into the HTML <head> after the default Argo CD styles, allowing your rules to override existing classes.

apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-cm
  namespace: argocd
data:
  ui.cssurl: "https://example.com/my-argo-cd.css"

When configured, the UI fetches the stylesheet on page load and applies it globally. According to the source in ui/embed.go, the server reads the UiCssURL field from settings and embeds it as a <link> tag in the served HTML.

Global Announcement Banners

You can display persistent banners across all Argo CD pages using five related ConfigMap keys. These banners appear as thin bars at the top or bottom of the interface.

• ui.bannerContent: The text or HTML emoji to display
• ui.bannerURL: Optional hyperlink when users click the banner
• ui.bannerPosition: Either "top" or "bottom" (defaults to top)
• ui.bannerPermanent: When set to "true", hides the close button

apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-cm
  namespace: argocd
data:
  ui.bannerContent: "🚧 Maintenance window – expect brief downtimes 🚧"
  ui.bannerURL: "https://status.example.com"
  ui.bannerPosition: "top"
  ui.bannerPermanent: "true"

The ArgoCDSettings struct in util/settings/settings.go defines these fields as UiBannerContent, UiBannerURL, UiBannerPosition, and UiBannerPermanent, mapping directly to the ConfigMap keys.

SSO Login Button Text

When using Dex or OIDC authentication, the default "Login via SSO" button label can be customized using the ui.loginButtonText key.

apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-cm
  namespace: argocd
data:
  ui.loginButtonText: "Log in with MyCompany"

This value populates the UiLoginButtonText field in the settings struct and renders in the login component managed by the React frontend.

Implementation Details

Understanding the source code architecture helps troubleshoot customization issues and predict reload behavior.

Settings Retrieval (util/settings/settings.go)

The core configuration logic resides in util/settings/settings.go, where the ArgoCDSettings struct declares the UI customization fields:

• UiCssURL string
• UiBannerContent string
• UiBannerURL string
• UiBannerPermanent bool
• UiBannerPosition string
• UiLoginButtonText string

A dedicated function populates these fields by reading the argocd-cm ConfigMap data keys and converting them to the appropriate Go types.

Static Asset Serving (ui/embed.go)

The ui/embed.go file implements the HTTP handler that serves the React application. During request processing, it checks the UiCssURL setting and injects a <link rel="stylesheet"> tag into the generated HTML. Similarly, banner settings are serialized into JavaScript variables accessible by the frontend components.

Frontend Components

Two React components consume these settings:

1. ui/src/app/shared/components/layout/layout.tsx: Manages the layout wrapper that renders banner elements based on the injected configuration
2. ui/src/app/settings/components/appearance-list/appearance-list.tsx: Provides a read-only view of current appearance settings in the UI settings page

Step-by-Step Configuration Examples

Mounting Local CSS Files

For air-gapped environments or complex stylesheets, mount a CSS file directly into the argocd-server pod rather than using external URLs.

First, create a ConfigMap containing your styles:

apiVersion: v1
kind: ConfigMap
metadata:
  name: argo-custom-css
  namespace: argargocd
data:
  my-styles.css: |
    .cd-header { background: #004080; }
    .application-list .application { border-radius: 4px; }

Patch the Argo CD server deployment to mount this ConfigMap as a volume:

volumes:
  - name: custom-css
    configMap:
      name: argo-custom-css
volumeMounts:
  - name: custom-css
    mountPath: /custom

Then reference the local path in argocd-cm:

data:
  ui.cssurl: "/custom/my-styles.css"

The UI server resolves this path relative to the container filesystem, serving the file directly without external network calls.

Complete Branding Example

Combine multiple customization options for a cohesive corporate branding experience:

apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-cm
  namespace: argocd
data:
  ui.cssurl: "https://assets.company.com/argo-theme.css"
  ui.bannerContent: "Production Environment - Authorized Access Only"
  ui.bannerPosition: "top"
  ui.bannerPermanent: "true"
  ui.loginButtonText: "Corporate SSO Login"

Applying and Reloading Changes

The Argo CD UI watches the argocd-cm ConfigMap for changes. When you update the ConfigMap via kubectl apply, the UI automatically picks up new banner text and stylesheet URLs within seconds without requiring a pod restart.

However, if you mount CSS files as volumes using the ConfigMap method, you must restart the argocd-server pod to remount the updated filesystem contents:

kubectl rollout restart deployment argocd-server -n argocd

For external CSS URLs, the browser caches the stylesheet according to standard HTTP caching headers. Force a hard refresh (Ctrl+F5 or Cmd+Shift+R) to see updates immediately.

Summary

• Modify argocd-cm: All UI customizations live in the Argo CD ConfigMap, not in source code or environment variables
• Custom CSS: Use ui.cssurl to load external stylesheets or local mounted files via util/settings/settings.go configuration
• Banners: Configure ui.bannerContent, ui.bannerURL, ui.bannerPosition, and ui.bannerPermanent for global announcements
• SSO Branding: Override the login button label with ui.loginButtonText to match corporate identity
• Hot Reloading: ConfigMap changes apply automatically, but volume-mounted files require pod restarts

Frequently Asked Questions

Where is the Argo CD UI customization configuration stored?

All customization settings reside in the argocd-cm ConfigMap within the Argo CD namespace. The argocd-server pod reads this ConfigMap at startup and watches it for changes, parsing keys like ui.cssurl and ui.bannerContent into the ArgoCDSettings struct defined in util/settings/settings.go.

Can I customize Argo CD UI without using an external URL for CSS?

Yes. You can mount a CSS file into the argocd-server pod using a Kubernetes ConfigMap or Secret, then reference the local filesystem path in the ui.cssurl key (for example, /custom/my-styles.css). This approach works in air-gapped environments and avoids external dependencies.

Do I need to restart Argo CD after changing the UI banner?

No. The Argo CD UI automatically detects changes to the argocd-cm ConfigMap and updates banners and stylesheet references without requiring a pod restart. However, if you modify a mounted CSS file volume, you must restart the argocd-server Deployment to remount the updated file into the container filesystem.

What CSS classes can I target when customizing Argo CD?

You can target any class visible in the React components, particularly those in ui/src/app/shared/components/layout/layout.tsx. Common overrides include .cd-header for the top navigation bar, .application-list for the applications grid, and .page__content for main content areas. Use browser developer tools to inspect the specific classes rendered by the Argo CD version you are running.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}