#Setting build time variables on GitHub Pages that activates a banner site wide on an Astro site

4 messages · Page 1 of 1 (latest)

fallen bear Jun 17, 2025, 12:34 PM

I'm looking for how to tell Astro to add certain components to my pages if during build time, a certain variable is set.

Mostly for GitHub Pages so I can add banners to my Astro & Starlight sites

foggy saddleBOT Jun 17, 2025, 12:34 PM

Hi @fallen bear. I'm kapa.ai, your friendly support bot. I will try to answer your question by searching through the knowledge base. :wave:

To activate a site-wide banner on your Astro (or Starlight) site during build time based on an environment variable—especially for deployments like GitHub Pages—you can use Astro’s environment variable support and Starlight’s built-in banner frontmatter.

1. Setting the Environment Variable in GitHub Actions

When deploying to GitHub Pages, you can set environment variables in your workflow file. For example, in .github/workflows/deploy.yml:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout your repository using git
        uses: actions/checkout@v4
      - name: Install, build, and upload your site
        uses: withastro/action@v3
        env:
          SHOW_BANNER: 'true'
          BANNER_CONTENT: '🚀 This is a site-wide banner! <a href="<https://example.com">Learn> more</a>'

This makes SHOW_BANNER and BANNER_CONTENT available as environment variables during the build process Configure a GitHub Action.

2. Accessing the Variable in Astro

Astro allows you to access environment variables at build time using import.meta.env. For example:

const showBanner = import.meta.env.SHOW_BANNER === 'true';
const bannerContent = import.meta.env.BANNER_CONTENT;

Only variables prefixed with PUBLIC_ are available on the client, but for build-time logic in your Astro components or pages, you can use any variable Getting environment variables.

3. Adding a Banner in Starlight

Starlight supports a banner frontmatter field for each page, which displays a banner at the top of the page banner frontmatter. To make this site-wide, you can:

Set the banner field in the frontmatter of every page (manual, not ideal for many pages).
Or, customize the default Banner component to check the environment variable and display the banner if set.

Example: Custom Banner Component

Override the default Banner component in Starlight to check the environment variable:

---
// src/components/Banner.astro
const showBanner = import.meta.env.SHOW_BANNER === 'true';
const bannerContent = import.meta.env.BANNER_CONTENT;
---

{showBanner && bannerContent && (
  <div class="banner" set:html={bannerContent} />
)}

Then, configure Starlight to use your custom Banner component.

Summary

Set your banner content as an environment variable in your GitHub Actions workflow.
Access the variable in your Astro or Starlight components using import.meta.env.
Use or override the Starlight Banner component to display the banner site-wide if the variable is set.

This approach ensures your banner appears only when the environment variable is set during the build, making it ideal for temporary announcements or environment-specific messaging.