Deploy context

pda deploy uploads a project folder to a Polaris server. The first deploy creates the project. Every later deploy replaces the project’s context with the folder you send.

Before you deploy

• An organization admin must create an organization API key. In Polaris, go to Settings › Organization › Organization API keys and select Generate API key. The key is shown only once. Polaris also shows the full pda deploy command to run with it.
• pda_config.yaml must have a project_name. Polaris uses it to find the project, so renaming it creates a new project.
• Secrets must be references such as {{ env('VAR') }}, never values.

Deploy by hand

From the project folder:

pda deploy https://polaris.example.com --api-key "$PDA_API_KEY"

Or from anywhere, with --path:

pda deploy https://polaris.example.com -k "$PDA_API_KEY" --path ./my-project

The CLI packs the folder into an archive and uploads it. It leaves out .git, .venv, node_modules, __pycache__, .env, *.pyc, and anything listed in .pdaignore. It prints whether the project was created or updated, and the project id.

Caution

Every deploy is a full replacement, not a merge. Files that exist only on the server are removed. Make Git the single source of truth for the project before you automate deploys.

Deploy from GitHub Actions

Deploy on every push to main, so the team’s Polaris always matches Git.

1. Add two repository secrets in GitHub (Settings › Secrets and variables › Actions): PDA_URL, the server URL, and PDA_API_KEY, the organization API key.
2. Add this workflow:

.github/workflows/pda-deploy.yml

name: pda deploy

on:
    push:
        branches: [main]
    workflow_dispatch:

concurrency:
    group: pda-deploy
    cancel-in-progress: false

jobs:
    deploy:
        runs-on: ubuntu-latest
        steps:
            - uses: actions/checkout@v4

            - uses: actions/checkout@v4
              with:
                  repository: <org>/<polaris-repository>
                  path: polaris-src

            - uses: astral-sh/setup-uv@v6

            - name: Install the Polaris CLI from source
              run: |
                  uv venv .venv
                  uv pip install --python .venv ./polaris-src/cli

            - name: pda deploy
              env:
                  PDA_URL: ${{ secrets.PDA_URL }}
                  PDA_API_KEY: ${{ secrets.PDA_API_KEY }}
              run: .venv/bin/pda deploy "$PDA_URL" --api-key "$PDA_API_KEY"

Guidelines:

• Trigger only on pushes to main. Do not deploy from pull requests, because that exposes the key to unreviewed code.
• Use one API key per repository, so you can revoke one without breaking others.
• Never print the key in logs.
• To refresh table docs on a schedule, use a separate sync workflow. Its commit to main triggers this deploy.

Troubleshooting

Message	Cause and fix
Authentication failed. Check your API key.	The key is wrong or revoked. Create a new one and update the secret.
No pda_config.yaml found in current directory	Run from the project folder, or pass --path.
pda_config.yaml is missing a 'project_name' field	Add project_name to the config.
Could not connect to <url>	Check the URL, and that the server is reachable from where the command runs.
The project is empty after a deploy	.pdaignore is too broad, or pda sync has not run.