Phala Cloud Documentation — Private AI on TEE

The Phala deploy action updates a CVM from your GitHub workflow. It installs the Phala CLI, runs phala deploy --json --wait, and reports the result as workflow outputs. You do not write any CLI commands yourself. Use it when you want the shortest path from a push to a deployed CVM. If you need to build images, run extra steps, or use another CI system, see Set Up a CI/CD Pipeline.

What do I need before I start?

A phala.toml file at the root of your repository. The action stops with an error if the file is missing. It tells the CLI which CVM to update. See phala.toml Configuration.
A Docker Compose file in the repository. The CLI reads it the same way it does for phala deploy.
A Phala Cloud API key.
An actions/checkout step before the action, so the files are on the runner.

On self-hosted runners, use Actions Runner 2.327.1 or newer. GitHub-hosted ubuntu-latest runners already work.

How do I add the API key?

Store the key as a repository secret. Do not put it in the workflow file.

In your GitHub repository, open Settings > Secrets and variables > Actions.
Select New repository secret.
Name it PHALA_API_KEY and paste your Phala Cloud API key.

If the key is ever exposed in logs or committed to a repository, create a new one in the Phala Cloud dashboard and replace the secret.

What does a minimal workflow look like?

name: Deploy to Phala Cloud

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: Phala-Network/phala-deploy-action@v3
        with:
          api-key: ${{ secrets.PHALA_API_KEY }}

To deploy only when your configuration changes, add a paths filter under push:

on:
  push:
    branches: [main]
    paths:
      - "phala.toml"
      - "docker-compose.yml"

What are the inputs?

Input	Required	Default	Description
`api-key`	Yes, unless you use keyless login		Your Phala Cloud API key. Pass it from a repository secret.
`envs`	No		Environment variables for the CVM, one `KEY=VALUE` per line.
`workspace`	No		Slug of the workspace to deploy into.
`cli-version`	No	`1.2.2`	The Phala CLI version the action installs.
`oidc-audience` (Beta)	No	`https://cloud.phala.com`	Audience of the GitHub OIDC token. Change it only if support tells you to. See Keyless login.

What are the outputs?

Read outputs from a step that has an id, for example steps.deploy.outputs.status.

Output	Description
`status`	`success`, `failed`, or `pending_approval`.
`result`	Full CVM information as JSON.
`app-id`	App ID of the CVM.
`vm-uuid`	VM UUID of the CVM.
`cvm-name`	Name of the CVM.
`dashboard-url`	Link to the CVM in the dashboard.
`compose-hash`	SHA256 hash of the normalized app compose.
`docker-compose-hash`	SHA256 hash of the raw `docker-compose.yml`.
`pre-launch-script-hash`	SHA256 hash of the pre-launch script.
`os-image`	OS image name.
`os-image-version`	OS image version.
`os-image-hash`	OS image hash.
`kms-type`	Key management type: `phala`, `ethereum`, or `base`.
`device-id`	Device ID of the node.
`commit-token`	Token for approving an update that needs on-chain approval. Empty otherwise.
`oidc-repository` (Beta)	Source repository, when the API returns it. May be empty.
`oidc-commit-sha` (Beta)	Source commit SHA, when the API returns it. May be empty.

status, app-id, vm-uuid, cvm-name, and dashboard-url come straight from the deploy result. The hash, OS image, kms-type, and device-id outputs come from a second request for the CVM’s details, which the action makes with your API key. If that request fails, the deploy still counts as successful, the action prints a warning, and those outputs are empty.

When does the job succeed or fail?

When the deployment is an update, the job waits for the real result. It does not stop after the update request is accepted.

Update finishes: the job succeeds with status=success.
Update fails or is cancelled: the job fails with status=failed, and the deploy output is printed in the job log.
Wait takes too long: the CLI waits up to 5 minutes for an update. After that the job fails, but the update may still be running. Check the CVM in the dashboard before you re-run the workflow.
Stopped CVM: the job waits for the CVM to return to the state it was in before the update. A stopped CVM stays stopped.

The action is built to update a CVM that already exists. Create the CVM first, for example with phala deploy -n <name> -c docker-compose.yml, and put its name in phala.toml. Then let the action update it on each push. A new CVM keeps booting after the command that creates it returns, so do not expect a first deployment to wait until the CVM is running. Open the CVM in the dashboard to follow it. Updating a CVM that is in error status is not supported yet. A fix is planned for the next CLI release. Until then, do not rely on the action to update a CVM in that state.

What happens when nothing changed?

If the configuration, compose file, and environment variables match what is already deployed, the job succeeds right away. The CVM is not restarted.

What if the CVM uses on-chain KMS?

An update to a CVM that uses on-chain KMS must be approved on-chain before it takes effect. The job does not fail in this case. It ends with status=pending_approval, prints the compose hash as a warning, and sets compose-hash and commit-token. Approve the update in the dashboard. Do not treat this status as a finished deployment.

      - uses: Phala-Network/phala-deploy-action@v3
        id: deploy
        with:
          api-key: ${{ secrets.PHALA_API_KEY }}

      - name: Remind the team to approve
        if: steps.deploy.outputs.status == 'pending_approval'
        run: echo "Approve compose hash ${{ steps.deploy.outputs.compose-hash }} in the dashboard."

How do I pass environment variables and secrets?

Use the envs input. Put one KEY=VALUE on each line, and take every value from a GitHub secret.

      - uses: Phala-Network/phala-deploy-action@v3
        with:
          api-key: ${{ secrets.PHALA_API_KEY }}
          envs: |
            DATABASE_URL=${{ secrets.DATABASE_URL }}
            REDIS_URL=${{ secrets.REDIS_URL }}

The action writes these lines to a .env file on the runner and passes it to the deploy. The CLI encrypts the values before it sends them, so they reach your CVM as encrypted secrets. Use a repository secret for each value. Never type a secret directly into the workflow file.

Which CLI version should I use?

Leave cli-version unset. The action installs the version it was tested with, which is 1.2.2. Because the action pins the version, a new CLI release does not change your deployments until you change the input. To use a different release, set the input to an exact version:

      - uses: Phala-Network/phala-deploy-action@v3
        with:
          api-key: ${{ secrets.PHALA_API_KEY }}
          cli-version: "1.2.2"

Use 1.2.1 or newer. Older versions do not wait correctly on stopped CVMs and do not check the update result with keyless login. Keyless login lets a workflow deploy without an API key. GitHub gives the job a short-lived token, and Phala Cloud accepts it from a GitHub repository that you registered for the app. This feature is in Beta. It is enabled per workspace, so contact support to turn it on for yours. To use it:

Ask support to enable it for your workspace.
Open your app in the dashboard and go to GitHub. This item appears only after support has enabled the feature.
Under GitHub repository, enter the repository that may deploy this app, in owner/repo format, and select Save. Phala Cloud asks you to confirm with a fresh two-factor verification when you save. You cannot save it with an API key.
Give the workflow the id-token: write permission, and contents: read for checkout.
Leave out api-key.

The page also has two optional fields. Only this git ref limits deploys to one ref, such as refs/heads/main. Only this workflow limits deploys to one workflow. Each app trusts one repository, and saving a new one replaces the old one. Select Remove to stop that repository from deploying the app.

name: Deploy to Phala Cloud

on:
  push:
    branches: [main]

permissions:
  contents: read
  id-token: write

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: Phala-Network/phala-deploy-action@v3

If the repository is registered for apps in more than one workspace, set the workspace input to the one you want. If you pass both an api-key and the permission, the CLI uses the API key. With keyless login the action reads the result from the deploy response only. The compose hash, OS image, kms-type, and device-id outputs are empty. oidc-repository and oidc-commit-sha are filled in only when the API returns them, so they can be empty too.

Troubleshooting

The job says phala.toml not found. Add phala.toml to the repository root, and make sure actions/checkout runs before the action. The job says no authentication method is available. Pass api-key and check that the secret name matches the one you created. For keyless login, check that the workflow has the id-token: write permission. The job fails after about 5 minutes. The update may still be running. Open the CVM in the dashboard and check its status before you run the workflow again. An output is empty. Hash, OS image, kms-type, and device-id outputs are filled in only when the action could fetch the CVM’s details. Look for a warning in the job log.

​What do I need before I start?

​How do I add the API key?

​What does a minimal workflow look like?

​What are the inputs?

​What are the outputs?

​When does the job succeed or fail?

​What happens when nothing changed?

​What if the CVM uses on-chain KMS?

​How do I pass environment variables and secrets?

​Which CLI version should I use?

​Keyless login with GitHub OIDC (Beta)

​Troubleshooting