How Do I Deploy Actors Using the GitHub Integration?

The Pod-OS Management Dashboard can deploy and Socket Actors directly from a GitHub repository. This integration does not apply to Evolutionary Neural Memory or other built-in actor types.

There are two integration patterns. Choose the one that matches how your software is packaged:

Both patterns are configured in the GitHub / GitLab Integration section when you deploy a new Gateway (Deploy Actor Network) or add an actor to an existing Gateway (Add Actor).

Reference examples (public repositories)

Pod-OS publishes minimal, production-shaped Socket actor examples you can clone, deploy from the dashboard, or use as templates for your own repos:

Both examples dial the Gateway, answer AIP health probes (StatusRequest → Status), and listen on :62312 for Kubernetes readiness. Each repository README includes build steps, dashboard field values, and podos CLI verification commands.

Prerequisites

Before you begin, make sure you have:

1. An active Pod-OS deployment with at least one Gateway
2. A user account with the developer, operator, tenant_administrator, or tenant_owner role
3. A GitHub repository containing your actor software
4. Build or higher subscription if you need to customize compute resources (Explore tier uses defaults)

Creating a GitHub Personal Access Token (PAT)

Some deployments require a GitHub PAT. The scope you need depends on the integration pattern:

Create a fine-grained PAT (recommended)

Fine-grained tokens limit access to specific repositories.

1. Sign in to GitHub and open Settings (your profile menu → Settings).
2. In the left sidebar, scroll to Developer settings.
3. Click Personal access tokens → Fine-grained tokens.
4. Click Generate new token.
5. Enter a Token name (for example, pod-os-actor-deploy).
6. Set an Expiration (90 days is a reasonable default; rotate before it expires).
7. Under Repository access, choose Only select repositories and pick the repo(s) your actor uses.
8. Under Permissions → Repository permissions, set Contents to Read-only.
   • For private GHCR images, also set Packages to Read-only under Account permissions (or the org that owns the package).
9. Click Generate token.
10. Copy the token immediately. GitHub shows it only once. If you lose it, you must generate a new token.

Create a classic PAT (alternative)

1. Go to Settings → Developer settings → Personal access tokens → Tokens (classic).
2. Click Generate new token (classic).
3. Add a note and expiration date.
4. Select scopes:
   • Category 1 (private GHCR image): check read:packages
   • Category 2 (private repo clone): check repo (full control of private repositories) or public_repo if the repository is public
5. Click Generate token and copy the value right away.

Retrieve or rotate a lost PAT

GitHub never displays an existing token again after creation. If you did not save it:

1. Revoke the old token under Settings → Developer settings → Personal access tokens.
2. Generate a new token using the steps above.
3. Update the credential in the Pod-OS dashboard by re-deploying or editing the actor and entering the new PAT.

Store PATs only in the Pod-OS dashboard credential fields or your organization's secret manager. Do not commit tokens to Git.

Use Case 1: Self-Registering Container

Use this when CI (typically GitHub Actions) builds a Docker image and pushes it to GitHub Container Registry (ghcr.io).

How it works

1. Your repository includes a Dockerfile and a GitHub Actions workflow.
2. CI builds the image and pushes to ghcr.io/<org>/<repo>:<tag>.
3. In the Pod-OS dashboard, you point the actor at the repository (and optionally override the image tag).
4. Pod-OS deploys the container and passes Gateway connection details via environment variables.
5. Your container connects to the Gateway and registers itself using the Pod-OS client libraries.

Environment variables available inside your container:

Example GitHub Actions workflow

Add .github/workflows/build-actor.yml to your repository:

name: Build and Push Actor Image

on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write
    steps:
      - uses: actions/checkout@v4
      - name: Log in to GHCR
        uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}
      - name: Build and push
        uses: docker/build-push-action@v5
        with:
          context: .
          push: true
          tags: |
            ghcr.io/${{ github.repository }}:${{ github.sha }}
            ghcr.io/${{ github.repository }}:main

Push to main, wait for the workflow to finish, then deploy from the dashboard using tag main or the commit SHA.

Reference example: podos-socket-self-register

The public repo PointOfData/podos-socket-self-register is a complete working example of this pattern. After CI pushes the image, configure a Socket actor in the dashboard:

• Integration Category: Self-registering container (image from CI)
• Repository URL: https://github.com/PointOfData/podos-socket-self-register
• Branch / Tag: main (or v1.0.1 for a pinned release)
• Container Image Override: ghcr.io/pointofdata/podos-socket-self-register:main

No PAT is required for the public repository or public GHCR image. See the repository README for local Docker run commands and health-check verification.

Deploy through the dashboard

Option A: New Gateway (Deploy Actor Network)

1. Log in to the Pod-OS Management Dashboard and open Dashboard.
2. Click Deploy Actor Network.
3. Configure your Gateway name and description.
4. Add a Shell or Socket actor.
5. Open Compute Configuration for that actor.
6. In GitHub / GitLab Integration, set:
   • Integration Category: Self-registering container (image from CI)
   • Repository URL: https://github.com/<org>/<repo>
   • Branch / Tag: main (or the tag your CI publishes)
   • Container Image Override (optional): ghcr.io/<org>/<repo>:main
7. If the image is private on GHCR:
   • Check Private image (requires image pull secret)
   • Enter your GitHub Username
   • Enter your GitHub PAT with read:packages scope
   • Optionally enter your Email
8. Click Save Configuration, then Deploy.

Option B: Add to an existing Gateway

1. Open Gateways and select your Gateway.
2. Click Add Actor.
3. Choose Socket (or Shell when available) and fill in name and description.
4. Expand GitHub / GitLab Integration and follow the same fields as Option A, step 6–7.
5. Click Deploy Actor.

Monitor progress in the streaming deployment view. When complete, your actor appears on the Actors page.

Use Case 2: Gateway Starts Software

Use this when your actor runs as a process started by the Gateway—not as a pre-built container you register yourself. Pod-OS clones your Git repository into the pod before the actor starts.

Important: This mode runs executables or scripts only. You cannot start a separate container image from actor_settings.ini.

How it works

1. An init container clones your repository into a shared volume (default path: /workspace/repo).
2. An optional Build Command compiles or prepares your code (for example, make or go build ./...).
3. The Gateway starts your software:
   • Shell actor: runs the Command Path you specify (for example, /workspace/repo/bin/run). Stdin/stdout carry message traffic.
   • Socket actor: runs your Startup Script, which starts an application listening on a socket; the Gateway connects after the app is ready.

Repository layout

Shell actor

• Include an executable or script at the path you configure (for example, bin/run).
• After clone, that path must exist at the Command Path you enter in the dashboard.

Socket actor

• Include a startup script or command that launches your application.
• The application must listen on the port the Gateway expects (default 62312).

Reference example: podos-socket-gateway-starts

The public repo PointOfData/podos-socket-gateway-starts is a complete working example of this pattern. The repository includes a prebuilt static binary and startup script—no build step is required at deploy time. Configure a Socket actor in the dashboard:

• Integration Category: Gateway starts software (clone repo)
• Repository URL: https://github.com/PointOfData/podos-socket-gateway-starts
• Branch / Tag: main (or v1.0.1 for a pinned release)
• Command Path / Startup Script Path: /workspace/repo/bin/start.sh
• Clone Path: /workspace/repo (default)

No PAT is required for the public repository. See the repository README for rebuilding the committed binary and verifying health with the podos CLI.

Deploy through the dashboard

Option A: New Gateway (Deploy Actor Network)

1. Log in and open Dashboard → Deploy Actor Network.
2. Add a Shell or Socket actor and open Compute Configuration.
3. In GitHub / GitLab Integration, set:
   • Integration Category: Gateway starts software (clone repo)
   • Repository URL: https://github.com/<org>/<repo>
   • Branch / Tag: main
   • Command Path (Shell) or path referenced by your startup script (Socket): /workspace/repo/bin/run
   • Clone Path: /workspace/repo (default)
   • Build Command (optional): e.g. cd /workspace/repo && make
   • Startup Script (Socket, optional): inline script content if not using a file in the repo
4. If the repository is private:
   • Enter your GitHub PAT with repository Contents: Read access (see Creating a GitHub PAT above).
   • Pod-OS stores the token in a Kubernetes secret and uses it only for the git-clone init container.
5. Click Save Configuration, then Deploy.

Option B: Add to an existing Gateway

1. Open Gateways → select Gateway → Add Actor.
2. Choose actor type, name, and description.
3. Configure GitHub / GitLab Integration as in Option A, step 3–4.
4. Click Deploy Actor.

Public repositories do not require a PAT. Private repositories require the PAT in step 4.

Choosing the Right Pattern

For copy-paste starting points, use the public reference examples above.

Troubleshooting

Security Notes

• PATs entered in the dashboard are stored as Kubernetes secrets in your tenant namespace, not in Neural Memory.
• Use fine-grained tokens scoped to the minimum repository and permissions required.
• Rotate tokens on a schedule and after team member departures.
• Never commit PATs to your repository or embed them in Docker images.

Next: Working with Socket Actors — understand how Socket Actors run your software and simplify your architecture.