Integrating your GitHub repository

Discover how to seamlessly integrate your GitHub repository with Zerops for automated builds and deployments.

You can choose between two powerful integration approaches: direct integration through the Zerops GUI for straightforward setup, or GitHub Actions for more customized deployment workflows.

This guide walks you through both integration methods, helping you choose and implement the approach that best fits your team's needs.

---

Prerequisites

Before starting the integration process, ensure your repository contains a valid zerops.yml configuration file located in the root directory. This file is essential for defining the build, deploy, and run processes. For detailed information on how to create or modify this file, refer to the Zerops YAML configuration guide.

---

Integration via Zerops GUI

Follow these steps to connect your GitHub repository directly with Zerops:

1. Access Service Settings

   • Log into the Zerops GUI
   • Select the relevant service from your dashboard.
   • In the left-hand menu, navigate to Build, Deploy, Run Pipeline Settings.

2. Connect to GitHub

   • Click Connect with a GitHub repository
   • You'll be prompted to authorize Zerops to access your GitHub account.
   • Grant the necessary permissions for Zerops to manage webhooks and fetch your code.

Note

Zerops requires full access to your repository in order to configure webhooks and pull the latest code changes. However, Zerops does not store your source code unless explicitly specified by you.

3. Select Repository and Trigger

   • Choose the GitHub repository you'd like to integrate with Zerops.
   • Configure the trigger that will initiate a build:
     • New tag: Builds are triggered whenever a new tag is created. This is the recommended option for production deployments.
       • You can optionally add a regular expression (regex) to filter specific tags.
     • Push to branch: Builds are triggered on every push to a specified branch, such as main or develop.

4. Finalize Setup

   • Review and confirm your settings to complete the integration process.
   • Your GitHub repository is now connected, and builds will be triggered based on the configured triggers.

---

Managing Your GitHub Integration

To skip triggering a build for a specific commit, you can include ci skip or skip ci in your commit message (case insensitive). This tells Zerops to ignore that particular commit during the build process.

Note

Although the webhook will still be delivered to GitHub, no action will be taken if ci skip is present in the commit message.

---

Disconnecting Your Repository

To disconnect your GitHub repository from Zerops:

1. Navigate to the Service Details page for the relevant service
2. Select Build, Deploy, Run Pipeline Settings from the menu.
3. Click Stop automatic build trigger

This action will remove the GitHub webhook and delete the associated integration configuration, effectively halting automated builds from this repository.

---

GitHub Workflow Integration

As an alternative to direct integration, you can use GitHub Actions to manage your deployments. This approach gives you more control over your deployment workflow and allows integration with other CI/CD processes.

GitHub Workflow using Zerops Actions

1. Create Workflow Configuration

   Create a new file at .github/workflows/deploy.yml in your repository:

   name: Deploy to Zerops
   
   on:
     push:
       branches:
         - main
   
   jobs:
     deploy:
       runs-on: ubuntu-latest
   
       steps:
         - name: Checkout code
           uses: actions/checkout@v3
   
         - name: Deploy with Zerops
           uses: zeropsio/actions@main
           with:
             access-token: ${{ secrets.ZEROPS_TOKEN }}
             service-id: your-service-id

2. Generate Access Token

   • Navigate to Settings > Access Token Management in your Zerops dashboard
   • Generate a new access token with appropriate permissions
   • Copy this token for use in GitHub secrets

3. Locate Service ID

   • Go to your service dashboard and click the three dots menu → Copy Service ID
   • Alternatively, find it in your service URL: https://app.zerops.io/service-stack/<your-service-id>/dashboard

4. Configure GitHub Secrets

   • Go to your GitHub repository settings
   • Navigate to Settings > Secrets and variables > Actions > Repository secrets
   • Add a new secret named ZEROPS_TOKEN with your access token value

Note

Keep your access token secure and never commit it directly to your repository. The token provides administrative access to your Zerops resources.

For more information about GitHub Actions, refer to the official GitHub Actions documentation.