Publish Static Site Actions

Forgejo Action for sebaTEC Forge to automatically publish static websites. Accepts artifacts from Hugo, Astro, or other Static Site Generators and provides a hosting URL. Enables error-free deployment without manual effort.

Quick Start

name: Deploy Preview
on:
  pull_request:
concurrency:
  group: "pages"
  cancel-in-progress: false

jobs:
  preview:
    if: forgejo.repository == 'sebatec-intern/sebatec.eu' && env.ACTIONS_ID_TOKEN_REQUEST_URL != ''
    runs-on: debian-stable
    enable-openid-connect: true
    steps:
      - uses: https://forge.sebatec.eu/actions/checkout@v7
        with:
          submodules: recursive
          fetch-depth: 0

      - uses: https://forge.sebatec.eu/actions/setup-node@v6
        with:
          node-version-file: .nvmrc
          cache: "npm"

      - name: Install dependencies
        run: npm ci

      - name: Get deploy URL
        id: get-config
        uses: https://forge.sebatec.eu/actions/publish-static-site/get-config@v1

      - name: Build
        run: npm run build
        env:
          ASTRO_SITE: ${{ steps.get-config.outputs.site_url }}

      - name: Deploy to server
        uses: https://forge.sebatec.eu/actions/publish-static-site/deploy@v1
        with:
          directory: dist

How It Works

The get-config action fetches the deployment URL from the backend and provides it as site_url. This URL is essential for static site generators that need absolute URLs for sitemaps, RSS feeds, or email links.

The deploy action uploads your static site to the backend. It sends only the changed files, making deployments fast and efficient. Optionally, it can post a comment on the pull request with the deployed URL.

Actions

get-config

Fetches the deployment URL from the backend.

Inputs

Name	Required	Description	Default
server	Yes	Base URL of the publish-static-site backend.	https://frg.stcld.eu/fastcgi-bin/publish-static-site

Outputs

Name	Description
site_url	Deployment URL provided by the backend.

deploy

Uploads static site artifacts to the backend.

Inputs

Name	Required	Description	Default
server	Yes	Base URL of the publish-static-site backend.	https://frg.stcld.eu/fastcgi-bin/publish-static-site
directory	Yes	Directory containing the generated static site (e.g., Astro dist/, Hugo public/).	.
comment	No	Whether to post a one-line comment on the source pull request with the deployed URL. Set to false to disable.	true

Outputs

Name	Description
site_url	Deployment URL provided by the backend.

cleanup

Removes every file uploaded under the current OIDC tenant by issuing an authenticated DELETE /files to the backend. Use it on pull_request: closed (or any other trigger) to remove a preview site when its PR is no longer relevant.

Inputs

Name	Required	Description	Default
server	Yes	Base URL of the publish-static-site backend.	https://frg.stcld.eu/fastcgi-bin/publish-static-site

Outputs

None — cleanup is a side-effecting primitive.

Example

name: Cleanup Preview
on:
  pull_request:
    types: [closed]
jobs:
  cleanup:
    if: env.ACTIONS_ID_TOKEN_REQUEST_URL != ''
    runs-on: debian-stable
    enable-openid-connect: true
    steps:
      - uses: https://forge.sebatec.eu/actions/publish-static-site/cleanup@v1

Security Considerations

Caution

OIDC must be enabled for these actions to work. Set enable-openid-connect: true at the workflow or job level.

The backend ensures secure deployments by validating requests and isolating each site to its own directory.

See Forgejo Actions Security - OpenID Connect for more details.

For general information about Forgejo Actions, refer to the Forgejo Actions Reference.

Backend Setup

For information on setting up the backend service, see backend/README.md.

Usage Examples

Example 1: npm-based Workflow

For projects using npm (e.g., Astro, Next.js, or other Node.js-based static site generators).

name: Deploy
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: debian-stable
    enable-openid-connect: true
    steps:
      - uses: https://forge.sebatec.eu/actions/checkout@v7
        with:
          submodules: recursive
          fetch-depth: 0

      - uses: https://forge.sebatec.eu/actions/setup-node@v6
        with:
          node-version-file: .nvmrc
          cache: "npm"

      - name: Install dependencies
        run: npm ci

      - name: Get deploy URL
        id: get-config
        uses: https://forge.sebatec.eu/actions/publish-static-site/get-config@v1

      - name: Build
        run: npm run build
        env:
          ASTRO_SITE: ${{ steps.get-config.outputs.site_url }}

      - name: Deploy
        uses: https://forge.sebatec.eu/actions/publish-static-site/deploy@v1
        with:
          directory: dist

Example 2: Hugo with Makefile

For projects using Hugo with a Makefile (see Hugo Deployment Makefile).

name: Deploy
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: debian-stable
    enable-openid-connect: true
    steps:
      - uses: https://forge.sebatec.eu/actions/checkout@v7
        with:
          submodules: recursive
          fetch-depth: 0

      - name: Install dependencies
        run: make setup

      - name: Get deploy URL
        id: get-config
        uses: https://forge.sebatec.eu/actions/publish-static-site/get-config@v1

      - name: Build
        run: make build
        env:
          HUGO_BASEURL: ${{ steps.get-config.outputs.site_url }}

      - name: Deploy
        uses: https://forge.sebatec.eu/actions/publish-static-site/deploy@v1
        with:
          directory: public

Contributing

We welcome contributions! Please follow these steps to contribute:

1. Fork the repository.
2. Create a new branch:

   git checkout -b feature-branch
   

3. Make your changes and commit them:

   git commit -m "Description of your changes"
   

4. Push to your fork:

   git push origin feature-branch
   

5. Create a pull request.

Guidelines

• Follow the existing code style.
• Write clear and concise commit messages.
• Ensure your changes do not break existing functionality.
• Update documentation as needed.

License

This project is licensed under the terms specified in the LICENSE file.