Actor source types
This section explains the various sources types available for Apify Actors and how to deploy an Actor from GitHub using CLI or Gist. Apify Actors supports four source types:
Web IDE
This is the default option when your Actor's source code is hosted on the Apify platform. It offers quick previews and updates to your source code, easy file and directory browsing, and direct testing of the INPUT_SCHEMA.json on the Apify platform.
A Dockerfile is mandatory for all Actors. When using the default NodeJS Dockerfile, you'll typically need main.js for your source code and package.json for npm package configurations.
For more information on creating custom Dockerfiles or using Apify's base images, refer to the Dockerfile and base Docker images documentation.
Git repository
Hosting your Actor's source code in a Git repository allows for multiple files and directories, a custom Dockerfile for build process control, and a user description fetched from README.md. Specify the repository location using the Git URL setting with https, git, or ssh protocols.
To deploy an Actor from a Git repository:
- In Apify Console, open your Actor and go to the Source tab.
- Set Source type to Git repository.
- Select Change in the Provider row and connect GitHub, GitLab, Bitbucket, or another Git provider.
- Enter the repository URL in the Git URL field.
To build from a specific branch or tag, add it to the URL as a fragment, for example #develop. To build from a directory, add the directory after the branch or tag, separated by a colon, for example #develop:some/dir.
For the full GitHub flow, including authorizing Apify and rebuilding on every push, see creating an Actor from a GitHub repository.
You can easily set up an integration where the Actor is automatically rebuilt on every commit to the Git repository. For more details, see GitHub integration.
Private repositories
When using a private Git repository for your Actor's source code, you need to configure a deployment key. This key grants Apify secure, read-only access to your repository.
Deployment keys are unique SSH keys that allow Apify to clone and build your Actor from a private repository.
How to configure deployment keys
To configure the deployment key for your Actor's source code you need to:
- In Apify Console, open your Actor and go to the Source tab.
- Set Source type to Git repository.
- Select deployment key.
- Copy the public SSH key and add it to your repository. The dialog links to instructions for GitHub, Bitbucket, and GitLab.
A private repository's Git URL must use the SSH format:
git@github.com:username/repo-name.gitgit@bitbucket.org:username/repo-name.gitgit@gitlab.com:username/repo-name.git
By using deployment keys, you enable secure, automated builds of your Actor from private repositories.
Apify generates a unique deployment key for each Actor, so you don't need to reuse a key across Actors. GitHub requires a dedicated key pair per repository, so add an Actor's key to a single repository. GitLab and Bitbucket allow the same key on multiple projects.
Actor monorepos
To manage multiple Actors in a single repository, use the dockerContextDir property in the Actor definition to set the Docker context directory (if not provided then the repository root is used). In the Dockerfile, copy both the Actor's source and any shared code into the Docker image.
To enable sharing Dockerfiles between multiple Actors, the Actor build process passes the ACTOR_PATH_IN_DOCKER_CONTEXT build argument to the Docker build.
It contains the relative path from dockerContextDir to the directory selected as the root of the Actor in Apify Console (the "directory" part of the Actor's git URL).
For an example, see the apify/actor-monorepo-example repository. To build Actors from this monorepo, you would set the source URL (including branch name and folder) as https://github.com/apify/actor-monorepo-example#main:actors/javascript-actor and https://github.com/apify/actor-monorepo-example#main:actors/typescript-actor respectively.
Zip file
Actors can also use source code from a Zip archive hosted on an external URL. This option supports multiple files and directories, allows for custom Dockerfile, and uses README.md for the Actor description. If not using a custom Dockerfile, ensure your main file is named main.js.
This source type is used automatically when you are using Apify-CLI and the source size exceeds 3MB.
GitHub Gist
For smaller projects, GitHub Gist offers a simpler alternative to full Git repositories or hosted Zip files. To use a GitHub Gist, create your Gist at https://gist.github.com/, set the Source type to GitHub Gist, and paste the Gist URL in the provided field.
Like other source types, Gists can include multiple files, directories, and a custom Dockerfile. The Actor description is taken from README.md.
By understanding these source types, you can choose the most appropriate option for hosting and deploying your Apify Actors. Each type offers unique advantages, allowing you to select the best fit for your project's size, complexity, and collaboration needs.