Skip to content

docs: continuous integration rewrite #1161

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Sep 5, 2024
Merged

docs: continuous integration rewrite #1161

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
eae6ab3
docs: continuous integration rewrite
TC-MO Aug 22, 2024
71da963
remove unnecessary new line
TC-MO Aug 22, 2024
e075077
add line numbers to yaml files
TC-MO Aug 22, 2024
45ce16a
Merge branch 'master' into deployment-continuous-integration
TC-MO Sep 5, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions apify-docs-theme/src/theme/custom.css
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1552,6 +1552,7 @@ html[data-theme='dark'] .runnable-code-block svg .apify-logo {
.prism-code.language-python .token-line::before,
.prism-code.language-dockerfile .token-line::before,
.prism-code.language-XML .token-line::before,
.prism-code.language-yaml .token-line::before,
.prism-code.language-js .token-line::before {
counter-increment: line-number;
content: counter(line-number);
Expand Down
173 changes: 74 additions & 99 deletions sources/platform/actors/development/deployment/continuous_integration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,133 +7,108 @@ sidebar_position: 2

# Continuous integration for Actors

**Learn how to integrate your Actors by setting up automated builds, deploys, and testing for your Actors using GitHub Actions or Bitbucket Pipelines.**
**Learn how to set up automated builds, deploys, and testing for your Actors using GitHub Actions or Bitbucket Pipelines.**

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

---

If you have a project consisting of several Actors, or even one Actor that requires frequent updates, you may want to automate some part of the development process. Instead of manually pushing your code, building each Actor, then testing it, you could perform the whole process whenever you run `git push`.
Automating your Actor development process can save time and reduce errors, especially for projects with multiple Actors or frequent updates. Instead of manually pushing code, building Actors, and running tests, you can automate these steps to run whenever you push code to your repository.

You can automate Actor builds and tests using your Git repository's automated workflows like [GitHub Actions](https://github.com/features/actions) or [Bitbucket Pipelines](https://bitbucket.org/product/features/pipelines).
This guide focuses on using GitHub Actions for continuous integration, but [we also have a guide for Bitbucket](https://help.apify.com/en/articles/1861038-setting-up-continuous-integration-for-apify-actors-on-bitbucket).

This article will focus on GitHub, but [we also have a guide for Bitbucket](https://help.apify.com/en/articles/1861038-setting-up-continuous-integration-for-apify-actors-on-bitbucket).
## Set up automated builds and tests

## TL;DR
To set up automated builds and tests for your Actors you need to:

Below is an example GitHub Actions workflow that will run your tests and build your Actor every time you push your code to GitHub. This workflow supports both **latest** and **beta** builds. Copy the code into **separate files** in your Actor repo's **.github/workflows** directory: e.g. **.github/workflows/latest.yml** and **.github/workflows/beta.yml**.
1. Create a GitHub repository for your Actor code.
1. Get your Apify API token from the [Apify Console](https://console.apify.com/account#/integrations)

Each time you push to the **main/master** branch, a new **latest** version of your Actor will be built. When you push to **develop**, a **beta** version will be built.
![Apify token in app](./images/ci-token.png)

<Tabs groupId="main">
<TabItem value="latest.yml" label="latest.yml">
1. Add your Apify token to GitHub secrets
1. Go to your repo > Settings > Secrets > New repository secret
1. Name the secret & paste in your token
1. Add the Builds Actor API endpoint URL to GitHub secrets
1. Use this format:

```yaml
name: Test and build latest version
on:
push:
branches:
- master
- main
jobs:
test:
runs-on: ubuntu-latest
steps:
# Install dependencies and run tests
- uses: actions/checkout@v2
- run: npm install && npm run test
# Build latest version
- uses: distributhor/workflow-webhook@v1
env:
webhook_url: ${{ secrets.LATEST_BUILD_URL }}
webhook_secret: ${{ secrets.APIFY_TOKEN }}
```cURL
https://api.apify.com/v2/acts/YOUR-ACTOR-NAME/builds?token=YOUR-TOKEN-HERE&version=0.0&tag=beta&waitForFinish=60
```

```
![Add build Actor URL to secrets](./images/ci-add-build-url.png)

</TabItem>
1. Name the secret
1. Create GitHub Actions workflow files:
1. In your repo, create the `.github/workflows` directory
2. Add `latest.yml` and `beta.yml` files with the following content

<Tabs groupId="main">
<TabItem value="latest.yml" label="latest.yml">

<TabItem value="beta.yml" label="beta.yml">
```yaml
name: Test and build latest version
on:
push:
branches:
- master
- main
jobs:
test:
runs-on: ubuntu-latest
steps:
# Install dependencies and run tests
- uses: actions/checkout@v2
- run: npm install && npm run test
# Build latest version
- uses: distributhor/workflow-webhook@v1
env:
webhook_url: ${{ secrets.LATEST_BUILD_URL }}
webhook_secret: ${{ secrets.APIFY_TOKEN }}

```yaml
name: Test and build beta version
on:
push:
branches:
- develop
jobs:
test:
runs-on: ubuntu-latest
steps:
# Install dependencies and run tests
- uses: actions/checkout@v2
- run: npm install && npm run test
# Build latest version
- uses: distributhor/workflow-webhook@v1
env:
webhook_url: ${{ secrets.BETA_BUILD_URL }}
webhook_secret: ${{ secrets.APIFY_TOKEN }}
```

```
With this setup, pushing to the `main` or `master` branch builds a new latest version.

</TabItem>
</Tabs>
</TabItem>

[Find the Bitbucket version here](https://help.apify.com/en/articles/1861038-setting-up-continuous-integration-for-apify-actors-on-bitbucket).
<TabItem value="beta.yml" label="beta.yml">

## Prerequisites
```yaml
name: Test and build beta version
on:
push:
branches:
- develop
jobs:
test:
runs-on: ubuntu-latest
steps:
# Install dependencies and run tests
- uses: actions/checkout@v2
- run: npm install && npm run test
# Build latest version
- uses: distributhor/workflow-webhook@v1
env:
webhook_url: ${{ secrets.BETA_BUILD_URL }}
webhook_secret: ${{ secrets.APIFY_TOKEN }}

To follow along, you will need a GitHub repository containing your [Actor](../index.md) code and your Apify API token.
```

[Find your Apify token in the Apify Console](https://console.apify.com/account#/integrations).
With this setup, pushing to the `develop` branch builds a new beta version.

![Apify token in app](./images/ci-token.png)
</TabItem>
</Tabs>

[Add the token to GitHub secrets](https://docs.github.com/en/actions/reference/encrypted-secrets#creating-encrypted-secrets-for-a-repository). Go to **your repo > Settings > Secrets > New repository secret**.
## GitHub integration

Add the [**Build Actor** API endpoint URL](/api/v2#/reference/actors/build-collection/build-actor) to GitHub secrets. Configure it to use your Actor's ID and your API token.
To set up automatic builds from GitHub:

```cURL
https://api.apify.com/v2/acts/YOUR-ACTOR-NAME/builds?token=YOUR-TOKEN-HERE&version=0.0&tag=beta&waitForFinish=60
```

![Add build Actor URL to secrets](./images/ci-add-build-url.png)

## Set up automatic builds

[//]: # (TODO: This duplicates somehow the above part)

Once you have your [prerequisites](#prerequisites), you can start automating your builds. You can use [webhooks](https://en.wikipedia.org/wiki/Webhook) or the [Apify CLI](/cli/) ([described in our Bitbucket guide](https://help.apify.com/en/articles/1861038-setting-up-continuous-integration-for-apify-actors-on-bitbucket)) in your Git workflow.

To use webhooks, you can use the [distributhor/workflow-webhook](https://github.com/distributhor/workflow-webhook) action, which uses the secrets described in the [prerequisites](#prerequisites) section.

```yaml
name: Build Actor
- uses: distributhor/workflow-webhook@v1
env:
webhook_url: ${{ secrets.[VERSION]_BUILD_URL }}
webhook_secret: ${{ secrets.APIFY_TOKEN }}
```

You can find your builds under the Actor's **Builds** section.

![An Actor's builds](./images/ci-builds.png)

## [](#github-integration) Automatic builds from GitHub

<iframe width="560" height="315" src="https://www.youtube-nocookie.com/embed/2I3DM8Nvu1M" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>

If the source code of an Actor is hosted in a [Git repository](#git-repository), it is possible to set up an integration so that the Actor is automatically rebuilt on every push to the Git repository. For that, you only need to set up a webhook in your Git source control system that will invoke the [Build Actor](/api/v2/#/reference/actors/build-collection/build-actor) API endpoint on every push.

For repositories on GitHub, you can use the following steps. First, go to the Actor detail page, open the **API** tab, and copy the **Build Actor** API endpoint URL. It should look something like this:

```text
https://api.apify.com/v2/acts/apify~hello-world/builds?token=<API_TOKEN>&version=0.1
```

Then go to your GitHub repository, click **Settings**, select **Webhooks** tab and click **Add webhook**. Paste the API URL to the **Payload URL** as follows:
1. Go to your Actor's detail page and coy the Build Actor API endpoint URL from the API tab.
1. In your GitHub repository, go to Settings > Webhooks > Add webhook.
1. Paste the API URL into the Payload URL field.

![GitHub integration](./images/ci-github-integration.png)

And that's it! Now your Actor should automatically rebuild on every push to the GitHub repository.
Now your Actor will automatically rebuild on every push to the GitHub repository.