Skip to content

github.mdx

Latest commit

 

History

History
330 lines (264 loc) · 11.7 KB

github.mdx

File metadata and controls

330 lines (264 loc) · 11.7 KB
title description tags
GitHub Service
Build and deploy services from GitHub repositories with Docker
schema
github
docker
deployment
build

import { Callout } from "nextra/components"; import { Tabs } from "nextra/components";

The github service type builds and deploys applications from a GitHub repository using a Dockerfile. This is the most common service type for application code that needs to be built from source.

Examples

<Tabs items={["Minimal", "With Deployment Options", "Complete"]}>

<Tabs.Tab> Minimal configuration with only required fields:

services:
  - name: "api"
    github:
      repository: "myorg/api" # Required - GitHub repo in owner/repo format
      branchName: "main" # Required - default branch to build
      docker: # Required - Docker build configuration
        defaultTag: "main" # Required - image tag, typically matches branch
        app: # Required - main application container
          dockerfilePath: "Dockerfile" # Required - path to Dockerfile
          ports:
            - 3000

</Tabs.Tab>

<Tabs.Tab> Configuration with deployment options:

services:
  - name: "api"
    github:
      repository: "myorg/api"
      branchName: "main"
      docker:
        defaultTag: "main"
        builder:
          engine: "buildkit" # Options: buildkit (default), codefresh, kaniko
        app:
          dockerfilePath: "Dockerfile"
          env:
            NODE_ENV: "production"
            LOG_LEVEL: "info"
          ports:
            - 3000
      deployment:
        public: true # Creates ingress for external access
        resource: # Custom CPU/memory allocation
          cpu:
            request: "100m"
            limit: "500m"
          memory:
            request: "256Mi"
            limit: "512Mi"
        readiness: # Health check configuration
          httpGet:
            path: "/health"
            port: 3000
          initialDelaySeconds: 10
          periodSeconds: 5

</Tabs.Tab>

<Tabs.Tab> Complete configuration with all options:

services:
  - name: "api"
    github:
      repository: "myorg/api"
      branchName: "main"
      docker:
        defaultTag: "main"
        builder:
          engine: "buildkit" # Options: buildkit (default), codefresh, kaniko
          resources: # Optional - custom CPU/memory for the build job
            requests:
              cpu: "1"
              memory: "2Gi"
            limits:
              cpu: "4"
              memory: "8Gi"
        # Init container - runs before main application (optional)
        init:
          dockerfilePath: "docker/migrate.dockerfile"
          command: "/bin/sh"
          arguments: "-c%%SPLIT%%npm run db:migrate" # Use %%SPLIT%% for spaces in arguments
          env:
            DATABASE_URL: "postgres://{{database_internalHostname}}:5432/app"
        # Main application container (required)
        app:
          dockerfilePath: "Dockerfile"
          command: "node" # Optional - override entrypoint
          arguments: "dist/main.js" # Optional - arguments to command
          env:
            NODE_ENV: "production"
            DATABASE_URL: "postgres://{{database_internalHostname}}:5432/app"
            REDIS_URL: "redis://{{cache_internalHostname}}:6379"
          ports:
            - 3000
            - 9090
      deployment:
        public: true # true = creates ingress, false = internal only
        capacityType: "spot" # Options: spot, on-demand
        resource: # Custom CPU/memory requests and limits
          cpu:
            request: "100m"
            limit: "1000m"
          memory:
            request: "256Mi"
            limit: "1Gi"
        readiness: # Health check - httpGet or tcpSocketPort
          httpGet:
            path: "/health"
            port: 3000
          initialDelaySeconds: 15 # Delay before first check
          periodSeconds: 10 # Check interval
          timeoutSeconds: 5 # Check timeout
          failureThreshold: 3 # Failures before unhealthy
        hostnames: # Optional - auto-constructed from global_config if omitted
          host: "api.example.com"
          defaultPublicUrl: "api.myapp.example.com"
        network: # Optional - advanced routing
          ipWhitelist:
            - "10.0.0.0/8"
          pathPortMapping: # Map URL paths to container ports
            "/api": 3000
            "/metrics": 9090
          grpc: # gRPC support
            enable: true
            host: "grpc.api.example.com"
        serviceDisks: # Optional - persistent volume mounts
          - name: "uploads" # Required - volume name
            mountPath: "/app/uploads" # Required - path in container
            storageSize: "5Gi" # Required - storage size
            accessModes: "ReadWriteOnce" # Optional - ReadWriteOnce or ReadWriteMany

</Tabs.Tab>

Docker Configuration

The docker section defines how the application is built and run.

docker.defaultTag

The default Docker image tag, typically matching the branch name.

docker.builder

Configuration for the Docker build process.

Field Type Description
engine string Build engine: buildkit (default), kaniko, codefresh
resources.requests object Minimum CPU/memory guaranteed for the build job
resources.limits object Maximum CPU/memory allowed for the build job

The resources field lets you configure CPU and memory for the build job container. Values use standard Kubernetes resource units (e.g., "500m" for CPU, "1Gi" for memory).

Precedence: Per-service resources in lifecycle.yaml take priority over values set in global_config. If neither is set, built-in defaults are used.

Engine Default CPU Request Default Memory Request Default CPU Limit Default Memory Limit
buildkit 500m 1Gi 2 4Gi
kaniko 300m 750Mi 1 2Gi 
docker:
  builder:
    engine: "buildkit"
    resources:
      requests:
        cpu: "1"
        memory: "2Gi"
      limits:
        cpu: "4"
        memory: "8Gi"

docker.app (Required)

Configuration for the main application container:

  • dockerfilePath - Required. Path to Dockerfile relative to repo root
  • command - Override container entrypoint
  • arguments - Arguments passed to the command. Use %%SPLIT%% as a delimiter for spaces (e.g., -c%%SPLIT%%npm run start)
  • env - Environment variables
  • ports - Exposed container ports

docker.init (Optional)

Configuration for an init container that runs before the main application. Uses the same fields as docker.app.

Deployment Options

The deployment section configures how the service is deployed to Kubernetes. All fields are optional.

public

Controls whether the service is exposed via ingress for external access.

  • true - Creates an ingress, service gets a public URL
  • false - Internal only, accessible only within the cluster

capacityType

Specifies the node capacity type for scheduling:

  • spot - Use spot/preemptible instances (cost-effective)
  • on-demand - Use on-demand instances (more reliable)

resource

CPU and memory requests and limits for the container:

Field Description
cpu.request Minimum CPU guaranteed (e.g., 100m)
cpu.limit Maximum CPU allowed (e.g., 1000m)
memory.request Minimum memory guaranteed (e.g., 256Mi)
memory.limit Maximum memory allowed (e.g., 1Gi)

readiness

Health check configuration to determine when the service is ready to receive traffic.

HTTP health check:

Field Description
httpGet.path HTTP endpoint path (e.g., /health)
httpGet.port Port to check

TCP health check:

Field Description
tcpSocketPort TCP port to check connectivity

Common fields:

Field Description
initialDelaySeconds Delay before first check
periodSeconds Interval between checks
timeoutSeconds Timeout for each check
successThreshold Consecutive successes to be healthy
failureThreshold Consecutive failures to be unhealthy

hostnames

Custom hostname configuration. If omitted, hostnames are auto-constructed from global_config values.

Field Description
host Custom hostname suffix
defaultInternalHostname Internal Kubernetes hostname
defaultPublicUrl Default public URL
acmARN AWS ACM certificate ARN for TLS

network

Advanced network configuration:

Field Description
ipWhitelist Array of allowed IP ranges (CIDR notation)
pathPortMapping Map URL paths to container ports
hostPortMapping Map hostnames to container ports
grpc.enable Enable gRPC support
grpc.host gRPC hostname

serviceDisks

Persistent volume mounts for stateful data:

Field Required Description
name Yes Volume name
mountPath Yes Path inside the container
storageSize Yes Storage size (e.g., 10Gi)
accessModes No ReadWriteOnce or ReadWriteMany
medium No Storage medium

Fields Reference

Required Fields

Field Type Description
repository string GitHub repository in owner/repo format
branchName string Branch to build from
docker object Docker build configuration (see above)

Optional Fields

Field Type Description
deployment object Deployment configuration (see above)
envLens boolean Enable environment lens ingress banner. Overrides the global features.envLens default.

Template Variables

Reference other services in your configuration using template variables. See the Template Variables guide for the complete list.

env:
  DATABASE_URL: "postgres://{{database_internalHostname}}:5432/app"
  CACHE_URL: "redis://{{cache_internalHostname}}:6379"
  FRONTEND_URL: "https://{{frontend_publicUrl}}"