---
name: apify-ci-integration
description: |-
  Configure CI/CD pipelines for Apify Actor builds and deployments.
  Use when automating Actor deployment via GitHub Actions, running
  integration tests against the live Apify API, or building CI/CD for
  scrapers that push to the Apify platform.
  Trigger with "apify CI", "apify GitHub Actions", "apify automated deploy",
  "CI apify", "apify pipeline", "auto deploy actor".
allowed-tools: Write, Bash(gh:*), Bash(npm:*)
version: 1.5.0
license: MIT
author: Jeremy Longshore <jeremy@intentsolutions.io>
tags:
  - saas
  - scraping
  - automation
  - apify
compatibility: Designed for Claude Code
title: apify-ci-integration
canonical_url: https://skilld.dev/gh/jeremylongshore/tons-of-skills-marketplace/apify-ci-integration
last_updated: 2026-10-07T06:06:28.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> Supporting files, fetch one when the Skill refers to it: [references/integration-tests.md](https://skilld.dev/api/skills-raw/jeremylongshore/tons-of-skills-marketplace/apify-ci-integration/references/integration-tests.md), [references/workflows.md](https://skilld.dev/api/skills-raw/jeremylongshore/tons-of-skills-marketplace/apify-ci-integration/references/workflows.md).
>
> If the user asked to install this Skill, run `npx skilld install jeremylongshore/tons-of-skills-marketplace/apify-ci-integration`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/apify-ci-integration`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/jeremylongshore/tons-of-skills-marketplace/apify-ci-integration) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/apify-ci-integration`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/apify-ci-integration --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/apify-ci-integration --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# Apify CI Integration

## Overview

Automate Apify Actor builds, tests, and deployments using GitHub Actions —
test-on-PR, deploy-on-merge, live-API integration testing, and Docker build
verification. Three workflow files do the work (test, deploy, verify-build);
full copy-paste-ready definitions live in
[references/workflows.md](https://skilld.dev/api/skills-raw/jeremylongshore/tons-of-skills-marketplace/apify-ci-integration/references/workflows.md).

## Prerequisites

- GitHub repository with Actions enabled
- Apify API token stored as a GitHub secret
- Actor code in the repository

## Authentication

CI authenticates to Apify with a personal API token, never a hard-coded
credential:

- Store the token as a GitHub Actions **secret** (`gh secret set APIFY_TOKEN`),
  and expose it to a job only via `env: APIFY_TOKEN: ${{ secrets.APIFY_TOKEN }}`.
- The Apify CLI reads it as `apify login --token $APIFY_TOKEN`; the REST API and
  `apify-client` read it from the `APIFY_TOKEN` environment variable.
- Use separate `APIFY_TOKEN_TEST` / `APIFY_TOKEN_PROD` secrets so integration
  runs never touch production data. Get tokens from Apify Console → Settings →
  Integrations.

## Instructions

### Step 1: Configure GitHub Secrets

```bash
# Store Apify token for CI
gh secret set APIFY_TOKEN --body "apify_api_YOUR_CI_TOKEN"

# Optional: separate tokens for test vs production
gh secret set APIFY_TOKEN_TEST --body "apify_api_test_token"
gh secret set APIFY_TOKEN_PROD --body "apify_api_prod_token"
```

### Step 2: Create the test workflow

Add `.github/workflows/apify-test.yml` with two jobs — `unit-tests` on every PR
and `integration-tests` gated to `push` (merge) events. The integration job
proves connectivity before running tests:

```yaml
      - name: Verify Apify connection
        run: |
          curl -sf -H "Authorization: Bearer $APIFY_TOKEN" \
            https://api.apify.com/v2/users/me | jq '.data.username'
```

Full two-job workflow: [references/workflows.md](https://skilld.dev/api/skills-raw/jeremylongshore/tons-of-skills-marketplace/apify-ci-integration/references/workflows.md) (Test Workflow).

### Step 3: Create the deploy workflow

Add `.github/workflows/apify-deploy.yml` — triggered on merges that touch
`src/**`, `package.json`, or `.actor/**` (plus `workflow_dispatch`). It builds,
tests, installs the Apify CLI, `apify push`es, then runs a minimal smoke call to
confirm the new build actually starts. Full definition:
[references/workflows.md](https://skilld.dev/api/skills-raw/jeremylongshore/tons-of-skills-marketplace/apify-ci-integration/references/workflows.md) (Deploy Workflow).

### Step 4: Write integration tests

Gate live-API tests on the token so they skip cleanly when it is absent:

```typescript
const SKIP_INTEGRATION = !process.env.APIFY_TOKEN;

describe.skipIf(SKIP_INTEGRATION)('Apify Integration', () => {
  it('should authenticate successfully', async () => {
    const user = await client.user().get();
    expect(user.username).toBeTruthy();
  });
});
```

The complete suite (auth, live Actor run, create/delete a named dataset with
cleanup) is in [references/integration-tests.md](https://skilld.dev/api/skills-raw/jeremylongshore/tons-of-skills-marketplace/apify-ci-integration/references/integration-tests.md).

### Step 5: Verify the Actor build

Add a `verify-build.yml` that `docker build`s the Actor image and boots it once
to confirm the entry point loads. Optionally add branch-protection rules that
require the CI contexts before merge. Both blocks:
[references/workflows.md](https://skilld.dev/api/skills-raw/jeremylongshore/tons-of-skills-marketplace/apify-ci-integration/references/workflows.md) (Actor Build Verification).

## Output

Applying this skill produces committed CI/CD infrastructure in the repository:

- `.github/workflows/apify-test.yml` — unit tests on every PR, integration tests
  on merge to `main`.
- `.github/workflows/apify-deploy.yml` — `apify push` + post-deploy smoke test on
  merge, plus manual `workflow_dispatch`.
- `.github/workflows/verify-build.yml` — Docker build + entry-point check on PRs.
- `tests/integration/apify.test.ts` — token-gated live-API integration suite.
- Configured GitHub secrets (`APIFY_TOKEN`, optional `_TEST` / `_PROD` variants)
  and, optionally, branch-protection requiring the CI checks to pass.

Once merged, every PR runs unit tests, every merge deploys and smoke-tests the
Actor, and a failed deploy surfaces a `::error::` annotation in the run log.

## Error Handling

| Issue | Cause | Solution |
|-------|-------|----------|
| `APIFY_TOKEN` not set | Secret not configured | `gh secret set APIFY_TOKEN` |
| Integration test timeout | Slow Actor run | Increase timeout, use smaller input |
| Docker build fails in CI | Local-only deps | Commit `package-lock.json` |
| `apify push` fails | Not logged in | Add `apify login --token` step |
| Flaky integration tests | External service issues | Add retries, use `test.retry(2)` |

## Examples

**Minimal test-on-PR gate** — the smallest useful setup is Step 1 (store the
secret) plus the `unit-tests` job from the test workflow. Every PR then runs
`npm ci && npm run build && npm test` before it can merge.

**Full deploy pipeline** — add the deploy workflow so a merge to `main` that
touches `src/**` builds, tests, runs `apify push`, then smoke-tests the new
build:

```yaml
      - name: Push Actor to Apify
        run: apify push

      - name: Verify deployment
        run: |
          ACTOR_ID=$(jq -r '.name' .actor/actor.json)
          apify actors call $ACTOR_ID \
            --input='{"startUrls":[{"url":"https://example.com"}],"maxItems":1}' \
            --timeout=120
```

**apify-client app (not Actor dev)** — for an app that *calls* Actors rather than
publishing one, mock `apify-client` in unit tests and gate a real-token
integration job to `main`. Full workflow:
[references/workflows.md](https://skilld.dev/api/skills-raw/jeremylongshore/tons-of-skills-marketplace/apify-ci-integration/references/workflows.md) (CI Configuration for apify-client Apps).

See [references/workflows.md](https://skilld.dev/api/skills-raw/jeremylongshore/tons-of-skills-marketplace/apify-ci-integration/references/workflows.md) for every full workflow
and [references/integration-tests.md](https://skilld.dev/api/skills-raw/jeremylongshore/tons-of-skills-marketplace/apify-ci-integration/references/integration-tests.md) for the
complete integration suite.

## Resources

- [GitHub Actions Documentation](https://docs.github.com/en/actions)
- [Apify CLI Reference](https://docs.apify.com/cli/docs/reference)
- [Actor Deployment](https://docs.apify.com/platform/actors/development/deployment)

## Next Steps

For runtime deployment patterns beyond CI wiring — release channels, versioned
Actor builds, and rollback — see the `apify-deploy-integration` skill in this
pack.
