CI/CD for Apify Actors: Auto-deploy from GitHub

Contains affiliate links. Disclosure.

Custom Actors should deploy like any other service: test on pull requests, ship on green main, and keep secrets out of git. Apify supports Git-backed sources, Build webhooks, the Apify CLI (apify push), and the official GitHub Action apify/push-actor-action.

Quick Answer

Deploy Apify Actors via GitHub CI/CD using the official Apify GitHub Action. Push code to GitHub → GitHub Actions runs apify push (via apify/push-actor-action) → Apify builds and deploys your Actor.

Official references: Continuous integration for Actors, GitHub integration, Apify CLI.

Feature overview

Feature	What it gives you
Git repository source	Apify pulls .actor/, Dockerfile, and sources straight from GitHub/GitLab/Bitbucket.
Build Actor webhook	Git host notifies Apify after each push; Apify queues a remote build.
apify/push-actor-action	Official Action that authenticates with your token and triggers the same push/build flow as the CLI.
apify push in CI	Full control (custom install steps, monorepos) when you need more than the Action defaults.
Version & build tags	Map Git tags and buildTag fields to release tracks like latest vs beta.

Method 1: Build from a linked Git repository

1. Create a repository with at least:
   • .actor/actor.json
   • Dockerfile (repository root or .actor/Dockerfile)
   • Input schema (commonly .actor/INPUT_SCHEMA.json unless overridden)
   • package.json (Node) or requirements.txt (Python)
2. In the Apify Console open your Actor → Source → choose Git repository.
3. Paste the HTTPS clone URL (public) or configure credentials / deploy keys for private repos.
4. Select the branch (main, develop, etc.).
5. Click Build so Apify clones the ref and builds the Docker image.

Recommended layout:

my-actor/
├── .actor/
│   ├── actor.json
│   └── INPUT_SCHEMA.json
├── src/
│   └── main.mjs
├── package.json
├── Dockerfile
└── README.md

OAuth-based linking is documented under the GitHub integration page.

Method 2: GitHub Actions with the official Apify Action (recommended)

The apify/push-actor-action wraps the same deployment path as the CLI. Minimal workflow:

name: Deploy Apify Actor

on:
  push:
    branches: [main]

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

      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 22

      - name: Push Actor to Apify
        id: push
        uses: apify/push-actor-action@master
        with:
          token: ${{ secrets.APIFY_TOKEN }}
          # Optional: actor-id: my-user/my-actor
          # Optional: working-directory: packages/apify-actor
          # Optional: build-tag: beta
          # Optional: version: 1.2.3

      - name: Print build metadata
        run: |
          echo "Build ${{ steps.push.outputs.build-id }} -> ${{ steps.push.outputs.build-status }}"

Setup checklist

1. Generate an Apify API token (Integrations → API tokens).
2. In GitHub: Settings → Secrets and variables → Actions → New repository secret → name APIFY_TOKEN.
3. Pin the Action ref to a published release (for example @v1.1.1) instead of @master once you validate the workflow. Semver tags reduce surprise upgrades. Check the releases page for the latest tag.

Action inputs (from the upstream README): token (required), optional actor-id, build-tag, version, working-directory. Outputs include build-id, build-number, and build-status.

Method 3: GitHub Actions running the Apify CLI

Use the CLI when you need custom install scripts, private npm registries, or monorepo prep before push:

name: Deploy Apify Actor (CLI)

on:
  push:
    branches: [main]

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

      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install dependencies
        run: npm ci

      - name: Run tests
        run: npm test

      - name: Install Apify CLI
        run: npm install -g apify-cli

      - name: Push Actor
        run: apify push
        env:
          APIFY_TOKEN: ${{ secrets.APIFY_TOKEN }}

apify login is optional in CI if you export APIFY_TOKEN. The CLI reads it automatically in modern versions.

Method 4: Pure webhook builds (no Action)

1. Apify Console → your Actor → API → copy the Build Actor endpoint.
2. GitHub repo → Settings → Webhooks → Add webhook.
3. Payload URL = Build endpoint, content type application/json, events Just the push event.

GitHub notifies Apify after every push; Apify clones the configured branch and builds. Pair this with branch protection so only reviewed code triggers production builds.

Bitbucket Pipelines (CLI pattern)

Bitbucket mirrors the CLI approach (official article):

pipelines:
  default:
    - step:
        name: Deploy to Apify
        image: node:20
        script:
          - npm install -g apify-cli
          - export APIFY_TOKEN=$APIFY_TOKEN
          - apify push

Store APIFY_TOKEN under Repository variables (secured).

Versioning and build tags

1. Git tags such as v1.4.0 mark releases for humans and changelog automation.
2. buildTag in .actor/actor.json (or Action input) separates streams (latest vs beta).
3. Publishing to the Store still requires meeting Store checklist items (metadata, README, pricing).

When Apify builds from linked Git, some metadata is controlled in the Console; when you deploy via CLI/Action, fields in actor.json are authoritative. Keep them in sync to avoid surprise version jumps.

Practices that keep CI/CD safe

• Never commit tokens. Use only GitHub/Bitbucket/GitLab secret stores.
• Run tests before push so broken Docker builds do not spam Apify.
• Ignore artifacts: .env, storage/, node_modules/ belong in .gitignore.
• Document memory defaults in README.md so reviewers know runtime cost implications (compute units).
• Use separate Actors or build tags for staging vs production workloads.

Two pipelines for two tracks

Point main at a latest build tag and develop at beta by maintaining two workflows (or conditional logic) with different build-tag inputs.

Open Apify Console

Frequently Asked Questions

It is apify/push-actor-action (see github.com/apify/push-actor-action). It authenticates with your Apify API token and triggers an Actor build, exposing build-id and build-status outputs.

Yes. Either call apify push yourself after installing apify-cli or use apify/push-actor-action, which performs the push/build on Apify’s side without you scripting CLI flags.

Yes. Link the Git repository directly in the Actor Source tab or configure a Build webhook so pushes trigger Apify-hosted builds with no workflow file.

Configure deploy keys or personal access tokens per Apify’s Git integration docs so Apify can clone the repo securely.

Yes. Apify supports multiple Git hosts for linked sources. For CI, mirror the CLI example in Bitbucket Pipelines or GitLab CI jobs.

Apify Console → your Actor → API tab → API Endpoints → copy the Build Actor URL and paste it into your Git provider’s webhook settings.