> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cnap.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# GitHub Actions Workflows

> Reusable GitHub Actions workflows for automatic builds and deployments with Railpack

<Card title="View Repository" icon="github" href="https://github.com/cnap-tech/actions">
  Browse the reusable GitHub Actions workflows repository
</Card>

CNAP provides reusable GitHub Actions workflows that automatically build Docker images from your source code using <Tooltip headline="Railpack" tip="Railpack is a modern build system that transforms application source code into container images without requiring a Dockerfile. It uses BuildKit to run build steps in parallel for faster builds, analyzes your code to create optimized build plans, and uses granular caching to speed up subsequent builds.">Railpack</Tooltip> and notify CNAP when new images are ready.

<Note>
  Already have a build pipeline? You can use individual reusable actions (like `notify-cnap`) to integrate CNAP notifications into your existing workflows. See [Using Individual Actions →](#using-individual-actions) for details.
</Note>

## What It Does

The CNAP GitHub Actions workflows automate the entire build and deployment pipeline:

1. **Checkout code** - Retrieves your repository code
2. **Language detection** - Railpack automatically detects your language and framework
3. **Build configuration** - Automatically configures build and runtime settings
4. **Image building** - Builds a production-ready Docker image using Railpack
5. **Registry push** - Pushes the image to GitHub Container Registry (GHCR)
6. **CNAP notification** - Automatically notifies CNAP about the new image

This means you can push code to GitHub and have containerized applications ready to deploy in CNAP without writing Dockerfiles or managing build pipelines.

## Quick Start

Add the workflow to your repository with zero configuration:

```yaml highlight={8,10-12} theme={null}
name: CNAP Build & Deploy
on:
  push:
    branches: [main]
  workflow_dispatch:

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

This workflow automatically:

* Detects your application's language and framework
* Builds a Docker image using Railpack
* Pushes to `ghcr.io/your-username/your-repo:sha-<commit-sha>`
* Notifies CNAP about the new build

## Configuration Options

You can customize the workflow behavior with optional inputs:

<ParamField path="build-context" type="string" default="./">
  Directory containing your application code. Use this for monorepos or projects with multiple applications.
</ParamField>

<ParamField path="build-command" type="string">
  Override Railpack's automatically detected build command. If not specified, Railpack analyzes your code to determine the build command.
</ParamField>

<ParamField path="start-command" type="string">
  Override Railpack's automatically detected start command. If not specified, Railpack analyzes your code to determine the start command.
</ParamField>

<ParamField path="build-apt-packages" type="string">
  Space-separated list of additional apt packages needed during the build phase (e.g., `python3-dev libpq-dev`).
</ParamField>

<ParamField path="runtime-apt-packages" type="string">
  Space-separated list of additional apt packages needed at runtime (e.g., `postgresql-client curl`).
</ParamField>

### Custom Build Context

For monorepos or projects with multiple applications:

```yaml theme={null}
jobs:
  deploy-api:
    uses: cnap-tech/actions/.github/workflows/cnap.yml@main
    permissions:
      contents: read
      packages: write
      id-token: write
    secrets: inherit
    with:
      build-context: './apps/api'

  deploy-web:
    uses: cnap-tech/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:

```yaml theme={null}
jobs:
  cnap:
    uses: cnap-tech/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](https://railpack.com) for complete language support and configuration options.

## How It Works with CNAP

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

1. **Workflow builds image** - The GitHub Actions workflow builds your application using Railpack
2. **Image pushed to GHCR** - The built image is pushed to GitHub Container Registry
3. **CNAP notified** - The workflow automatically notifies CNAP about the new build
4. **Build appears in CNAP** - The build shows up in your product's build history
5. **Ready to deploy** - You can select the new build when creating or updating installations

<Note>
  The workflow uses OIDC authentication to securely notify CNAP without requiring API keys or secrets. The `id-token: write` permission enables this secure authentication method.
</Note>

## Integration with CNAP Products

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

1. **Repository connected** - CNAP connects to your GitHub repository via GitHub App
2. **Builds detected** - CNAP automatically detects builds from the workflow
3. **Images available** - Built images appear in the build selection interface
4. **Automatic updates** - New builds automatically appear when the workflow runs

You don't need to manually configure the workflow—CNAP 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 just need to notify CNAP about new images.

### Notify CNAP After Existing Build

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

```yaml highlight={20-23} theme={null}
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 CNAP
        uses: cnap-tech/actions/.github/actions/notify-cnap@main
        with:
          image: ghcr.io/${{ github.repository }}:${{ github.sha }}
          image-tag: ${{ github.sha }}
```

#### notify-cnap Action Parameters

<ParamField path="image" type="string" required>
  Full Docker image name including registry and tag (e.g., `ghcr.io/owner/repo:sha-abc123`).
</ParamField>

<ParamField path="image-tag" type="string" required>
  Image tag, usually the commit SHA. This is used by CNAP to identify the specific build.
</ParamField>

<ParamField path="notify-url" type="string" default="https://cnap.tech/api/github/build-notify">
  CNAP API URL for build notifications. Only change this if you're using a custom CNAP instance.
</ParamField>

### Available Actions

The repository provides these reusable actions:

| Action                     | Description                           | Use Case                                                         |
| -------------------------- | ------------------------------------- | ---------------------------------------------------------------- |
| `notify-cnap`              | Sends build notification to CNAP API  | Use at the end of any pipeline that builds Docker 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 Build-Railpack Action

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

```yaml highlight={10-13,19-22} theme={null}
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: cnap-tech/actions/.github/actions/setup-buildkit@main

      - name: Build with Railpack
        uses: cnap-tech/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 CNAP
        uses: cnap-tech/actions/.github/actions/notify-cnap@main
        with:
          image: ghcr.io/${{ github.repository }}:${{ github.sha }}
          image-tag: ${{ github.sha }}
```

#### build-railpack Action Parameters

<ParamField path="image-name" type="string" required>
  Full Docker image name including registry and tag (e.g., `ghcr.io/owner/repo:sha-abc123`).
</ParamField>

<ParamField path="build-context" type="string" default="./">
  Directory containing application code. Use this for monorepos or projects with multiple applications.
</ParamField>

<ParamField path="build-command" type="string">
  Override Railpack's automatically detected build command. If not specified, Railpack analyzes your code to determine the build command.
</ParamField>

<ParamField path="start-command" type="string">
  Override Railpack's automatically detected start command. If not specified, Railpack analyzes your code to determine the start command.
</ParamField>

## Advanced Usage

### Custom Build Commands

Override Railpack's automatic detection:

```yaml theme={null}
with:
  build-command: 'npm run build:production'
  start-command: 'node server.js'
```

### Multiple Environments

Deploy different branches to different environments:

```yaml theme={null}
on:
  push:
    branches: [main, staging]

jobs:
  cnap:
    uses: cnap-tech/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' }}
```

## Related Topics

* [GitHub Integration →](/platform/github-integration) - Learn how to connect GitHub repositories to CNAP
* [Application Sources →](/app-sources) - Understand GitHub repository sources
* [Generic App Chart →](/tools/generic-chart) - See how GitHub deployments use the generic chart
* [Create a Product →](/products) - Create products from GitHub repositories