GitHub build workflows

A GitHub Actions workflow checking out code, building a container image, pushing to a registry, and notifying Akua that a new image is ready

View repository

Browse the reusable GitHub Actions workflows repository.

Akua provides reusable GitHub Actions workflows that build container images from your source code using and notify Akua when new images are ready for Package generation.

Already have a build pipeline? You can use individual reusable actions to integrate Akua notifications into your existing workflows. The current reusable workflow and action names still use legacy names such as cnap.yml and notify-cnap. See Using individual actions for details.

What it does

The Akua GitHub Actions workflows automate the image build path:

Checkout code: Retrieves your repository code.
Language detection: Railpack automatically detects your language and framework.
Build configuration: Uses Railpack defaults unless you override build or runtime settings.
Image building: Builds a production-ready Docker image using Railpack.
Registry push: Pushes the image to GitHub Container Registry (GHCR).
Akua notification: Notifies Akua that the new image can be used by the Package.

This means you can push code to GitHub and have container images ready for Akua Package generation without writing Dockerfiles or managing build pipelines.

Quick start

Add the workflow to your repository with the required permissions:

name: Akua Build Image
on:
  push:
    branches: [main]
  workflow_dispatch:

jobs:
  cnap:
    uses: akua-dev/actions/.github/workflows/cnap.yml@main
    permissions:
      contents: read
      packages: write
      id-token: write
    secrets: inherit

This workflow:

Detects your application’s language and framework when Railpack supports it.
Builds a container image using Railpack.
Pushes to ghcr.io/your-username/your-repo:sha-<commit-sha>.
Notifies Akua about the new build.

Configuration options

You can customize the workflow behavior with optional inputs:

string

default:"./"

Directory containing your application code. Use this for monorepos or projects with multiple applications.

string

Override Railpack’s automatically detected build command. If not specified, Railpack analyzes your code to determine the build command.

string

Override Railpack’s automatically detected start command. If not specified, Railpack analyzes your code to determine the start command.

string

Space-separated list of additional apt packages needed during the build phase (for example, python3-dev libpq-dev).

string

Space-separated list of additional apt packages needed at runtime (for example, postgresql-client curl).

Custom build context

For monorepos or projects with multiple applications:

jobs:
  deploy-api:
    uses: akua-dev/actions/.github/workflows/cnap.yml@main
    permissions:
      contents: read
      packages: write
      id-token: write
    secrets: inherit
    with:
      build-context: './apps/api'

  deploy-web:
    uses: akua-dev/actions/.github/workflows/cnap.yml@main
    permissions:
      contents: read
      packages: write
      id-token: write
    secrets: inherit
    with:
      build-context: './apps/web'

Custom dependencies

Add system packages for build or runtime:

jobs:
  cnap:
    uses: akua-dev/actions/.github/workflows/cnap.yml@main
    permissions:
      contents: read
      packages: write
      id-token: write
    secrets: inherit
    with:
      build-apt-packages: 'python3-dev libpq-dev'
      runtime-apt-packages: 'postgresql-client'

Supported languages

Railpack supports 10+ languages and frameworks with automatic detection:

Node.js: Express, Next.js, SvelteKit, Remix, Nuxt
Python: Django, FastAPI, Flask
Go: Gin, Echo, Chi
PHP: Laravel, Symfony
Java: Spring Boot, Quarkus
Ruby: Rails, Sinatra
Rust: Actix, Rocket, Axum
Deno: Web frameworks
Elixir: Phoenix
Static files: HTML, CSS, JavaScript
Shell scripts: Bash applications

See the Railpack documentation for complete language support and configuration options.

How it works with Akua

When you connect a GitHub repository to Akua and the workflow runs:

Workflow builds image: The GitHub Actions workflow builds your application using Railpack.
Image pushed to GHCR: The built image is pushed to GitHub Container Registry.
Akua notified: The workflow automatically notifies Akua about the new build.
Build appears in Akua: The build shows up in your source’s build history.
Ready to package: You can select the new build when creating a Package version.

The workflow uses OIDC authentication to securely notify Akua without requiring API keys or secrets. The id-token: write permission enables this secure authentication method.

Integration with Akua products

When you create a product in Akua using a GitHub repository source:

Repository connected: Akua connects to your GitHub repository via GitHub App.
Builds detected: Akua automatically detects builds from the workflow.
Images available: Built images appear in the build selection interface.
Build updates: New builds appear when the workflow runs. Create a new Package version or repository change request when a build should reach an installation.

You do not need to manually configure the workflow in most cases. Akua handles the integration automatically when you connect a GitHub repository.

Using individual actions

The reusable workflow is composed of individual reusable actions that you can use independently in your existing pipelines. This is useful when you already have a build process and need to notify Akua about new images.

Notify Akua after an existing build

If you already have a workflow that builds container images, you can use the notify-cnap action to notify Akua at the end of your pipeline:

name: Build and deploy

on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write
      id-token: write
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Build Docker image
        run: |
          docker build -t ghcr.io/${{ github.repository }}:${{ github.sha }} .
          docker push ghcr.io/${{ github.repository }}:${{ github.sha }}

      - name: Notify Akua
        uses: akua-dev/actions/.github/actions/notify-cnap@main
        with:
          image: ghcr.io/${{ github.repository }}:${{ github.sha }}
          image-tag: ${{ github.sha }}

notify-cnap action parameters

string

required

Full Docker image name including registry and tag (for example, ghcr.io/owner/repo:sha-abc123).

string

required

Image tag, usually the commit SHA. This is used by Akua to identify the specific build.

string

default:"https://akua.dev/api/github/build-notify"

Akua API URL for build notifications. Only change this if you’re using a custom Akua instance.

Available actions

The repository provides these reusable actions:

Action	Description	Use case
`notify-cnap`	Sends build notification to Akua API	Use at the end of any pipeline that builds container images
`build-railpack`	Builds a Docker image using Railpack	Use when you want Railpack builds but need custom workflow steps
`setup-buildkit`	Starts a BuildKit container	Use when you need BuildKit for custom builds
`stop-buildkit`	Stops the BuildKit container	Use to clean up BuildKit after builds
`generate-railpack-config`	Generates Railpack configuration file	Use when you need custom Railpack config

Using the build-railpack action

If you want to use Railpack for building but need more control over your workflow:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Install Railpack
        run: curl -sSL https://railpack.com/install.sh | bash

      - name: Setup BuildKit
        uses: akua-dev/actions/.github/actions/setup-buildkit@main

      - name: Build with Railpack
        uses: akua-dev/actions/.github/actions/build-railpack@main
        with:
          image-name: ghcr.io/${{ github.repository }}:${{ github.sha }}
          build-context: './src'

      - name: Push image
        run: docker push ghcr.io/${{ github.repository }}:${{ github.sha }}

      - name: Notify Akua
        uses: akua-dev/actions/.github/actions/notify-cnap@main
        with:
          image: ghcr.io/${{ github.repository }}:${{ github.sha }}
          image-tag: ${{ github.sha }}

build-railpack action parameters

string

required

Full Docker image name including registry and tag (for example, ghcr.io/owner/repo:sha-abc123).

string

default:"./"

Directory containing application code. Use this for monorepos or projects with multiple applications.

string

Override Railpack’s automatically detected build command. If not specified, Railpack analyzes your code to determine the build command.

string

Override Railpack’s automatically detected start command. If not specified, Railpack analyzes your code to determine the start command.

Advanced usage

Custom build commands

Override Railpack’s automatic detection:

with:
  build-command: 'npm run build:production'
  start-command: 'node server.js'

Multiple environments

Deploy different branches to different environments:

on:
  push:
    branches: [main, staging]

jobs:
  cnap:
    uses: akua-dev/actions/.github/workflows/cnap.yml@main
    permissions:
      contents: read
      packages: write
      id-token: write
    secrets: inherit
    with:
      build-context: ${{ github.ref == 'refs/heads/main' && './apps/prod' || './apps/staging' }}

GitHub integration

Connect GitHub repositories to Akua.

App sources

GitHub repository sources.

Container image sources

How GitHub builds and Docker images become Package versions.

Create a product

Create products from GitHub repositories.

Installations

Package authoring

Repository delivery

Automation

View repository

What it does

Quick start

Configuration options

Custom build context

Custom dependencies

Supported languages

How it works with Akua

Integration with Akua products

Using individual actions

Notify Akua after an existing build

notify-cnap action parameters

Available actions

Using the build-railpack action

build-railpack action parameters

Advanced usage

Custom build commands

Multiple environments

GitHub integration

App sources

Container image sources

Create a product

View repository

​What it does

​Quick start

​Configuration options

​Custom build context

​Custom dependencies

​Supported languages

​How it works with Akua

​Integration with Akua products

​Using individual actions

​Notify Akua after an existing build

​notify-cnap action parameters

​Available actions

​Using the build-railpack action

​build-railpack action parameters

​Advanced usage

​Custom build commands

​Multiple environments

​Related topics

GitHub integration

App sources

Container image sources

Create a product

What it does

Quick start

Configuration options

Custom build context

Custom dependencies

Supported languages

How it works with Akua

Integration with Akua products

Using individual actions

Notify Akua after an existing build

notify-cnap action parameters

Available actions

Using the build-railpack action

build-railpack action parameters

Advanced usage

Custom build commands

Multiple environments

Related topics