Koyeb Deploy GitHub Action

This action builds and deploys an application from a GitHub repository or Docker registry to Koyeb.

Usage

Before you can use the Koyeb Deploy Action, you first need to install and configure the Koyeb CLI.

- name: Install and configure the Koyeb CLI
  uses: koyeb-community/koyeb-actions@v2
  with:
    api_token: "${{ secrets.KOYEB_API_TOKEN }}"

Make sure to set the KOYEB_API_TOKEN secret in your repository. To generate a Koyeb token, go to the API access tokens settings in the Koyeb control panel.

After the step that installs the Koyeb CLI, add the following step to your workflow:

- name: Build and deploy the application to Koyeb
  uses: koyeb/action-git-deploy@v1
  with:
    service-env: PORT=8000
    service-ports: "8000:http"
    service-routes: "/:8000"

The service-env, service-ports, and service-routes parameters are optional, but should match the needs of your application. The defaults provided are unlikely to work for most applications.

Specify exactly one deployment source:

• Git source: use git-url (default behavior)
• Docker source: use docker

docker and git-* options are mutually exclusive.

Optional Parameters

The following optional parameters can be added to the with block:

Name	Description	Default Value
app-name	The name of the application	<repo>-<branch>
service-name	Name of the Koyeb service to be created	${{github.ref_name}}
service-type	Type of service to create ("web", "worker", or "sandbox")	web
build-timeout	Number of seconds to wait for the build before timing out and failing	900 (15 min)
healthy-timeout	Number of seconds to wait for the service to become healthy before timing out and failing	900 (15 min)
service-env	A comma-separated list of KEY=value pairs to set environment variables for the service	No env
service-instance-type	The type of instance to use to run the service - Full list of instances	nano
service-regions	A comma-separated list of region identifiers to specify where the service should be deployed Full list of regions	fra
service-ports	A comma-separated list of port:protocol pairs to specify the ports and protocols to expose for the service	80:http
service-routes	A comma-separated list of <path>:<port> pairs to specify the routes to expose for the service	/:80
service-checks	A comma-separated list of <port>:http:<path> or <port>:tcp pairs to specify the healthchecks for the service	No healthchecks
service-checks-grace-period	A comma-separated list of <healthcheck>=<seconds> values to configure healthcheck grace periods	Empty string
service-proxy-ports	A comma-separated list of <port>[:tcp] values to configure proxy ports	Empty string
service-volumes	A comma-separated list of <volume>:<path> values to attach volumes	Empty string
service-scale	Set both min and max scale values	Empty string
service-min-scale	Set minimum number of instances	Empty string
service-max-scale	Set maximum number of instances	Empty string
service-autoscaling-average-cpu	Target CPU usage percentage for autoscaling	Empty string
service-autoscaling-average-mem	Target memory usage percentage for autoscaling	Empty string
service-autoscaling-concurrent-requests	Target concurrent requests for autoscaling	Empty string
service-autoscaling-requests-per-second	Target requests per second for autoscaling	Empty string
service-autoscaling-requests-response-time	Target p95 response time in milliseconds for autoscaling	Empty string
service-deployment-strategy	Deployment strategy (rolling, blue-green, immediate)	Empty string
service-light-sleep-delay	Delay before entering light sleep (for example 1m, 5m, 1h, 0)	Empty string
service-deep-sleep-delay	Delay before entering deep sleep (for example 5m, 30m, 1h, 0)	Empty string
service-delete-after-delay	Automatically delete service after this duration (for example 1h, 24h, 0)	Empty string
service-delete-after-inactivity-delay	Automatically delete service after inactivity for this duration (for example 1h, 24h, 0)	Empty string
privileged	Whether to run the service in privileged mode	false
skip-cache	Whether skip the cache when building the service	false

If you want to deploy a GitHub repository, you can also add the following parameters:

Name	Description	Default Value
git-url	The URL of the GitHub repository to build	github.com/<organization>/<repo>
git-workdir	Directory inside the repository to clone	Empty string, which represents the root directory
git-branch	The Git branch to deploy	${{ github.ref_name }}
git-sha	The Git SHA to deploy	Empty string, which represents the latest commit of the branch
git-builder	Builder to use (buildpack or docker)	buildpack

By default, git-builder is buildpack. You can also add:

Name	Description	Default Value
git-build-command	Command to build the application	Empty string
git-run-command	Command to run the application	Empty string

If instead you want your GitHub repository to use the docker builder, set the parameter git-builder to docker. You can also add:

Name	Description	Default Value	Example
git-docker-command	Docker CMD	Empty string	'nginx -g \"daemon off;\"'
git-docker-dockerfile	Dockerfile to build	Dockerfile
git-docker-entrypoint	Docker ENTRYPOINT	Empty string	/docker-entrypoint.sh
git-docker-target	Docker target to build	Empty string

If you want to deploy a Docker image and not a GitHub repository, you can set the following parameters:

Name	Description	Default Value	Example
docker	The docker image to deploy	Empty string	"user/repo-name:tag"
docker-entrypoint	Docker ENTRYPOINT	Empty string	'nginx -g \"daemon off;\"'
docker-command	Docker CMD	Empty string	/docker-entrypoint.sh
docker-private-registry-secret	Secret to authenticate to the private registry - Stringyfied name of the secret created in the admin	Empty string	"user-docker-credentials"

Example: deploying a service to Koyeb

name: Deploy to Koyeb

on:
  push:
    branches:
      - '*'

jobs:
  deploy:
    runs-on: ubuntu-latest
    concurrency:
      group: "${{ github.ref_name }}"
      cancel-in-progress: true
    steps:
      - name: Install and configure the Koyeb CLI
        uses: koyeb-community/koyeb-actions@v2
        with:
          api_token: "${{ secrets.KOYEB_API_TOKEN }}"

      - name: Build and deploy the application to Koyeb
        uses: koyeb/action-git-deploy@v1
        with:
          app-name: my-koyeb-app
          service-name: my-koyeb-service
          service-env: FOO=bar,BAZ=qux
          service-ports: "80:http,8080:http"
          service-routes: "/api:80,/docs:8080"
          service-checks: "8000:http:/,8001:tcp"

Use secrets

Previously, we showed how to configure environment variables for your projects. For secrets variables, you can first create a Koyeb secret with the action-git-deploy/secret action:

- name: Create application secret
  uses: koyeb/action-git-deploy/secret@v1
  with:
    secret-name: MY_SECRET
    secret-value: "${{ secrets.DATABASE_URL }}"

Afterwards, you can use this secret as an environment variable for your service:

- name: Build and deploy the application to Koyeb
  uses: koyeb/action-git-deploy@v1
  with:
    [...]
    service-env: ENV_VAR=@MY_SECRET

Cleaning up Services

After deploying a service to Koyeb, you may want to remove it when it is no longer needed. To do this, you can use the koyeb/action-git-deploy/cleanup action. Here's an example of how to use this action:

- name: Install and configure the Koyeb CLI
  uses: koyeb-community/koyeb-actions@v2
  with:
    api_token: "${{ secrets.KOYEB_API_TOKEN }}"

- name: Clean up Koyeb Service
  uses: koyeb/action-git-deploy/cleanup@v1

The first step installs the CLI, which is required to remove the service. The second step performs the cleanup. Optionally, you can provide the app-name parameter (which defaults to <repo>/<branch>) to specify the name of the application to remove.

Example: removing a service when a ref is deleted

To remove a Koyeb service when a branch or tag is deleted, you can use the delete event in your workflow file. Here's an example of how to do this:

name: Cleanup Koyeb application

on:
  delete:
    branches:
      - '*'

jobs:
  cleanup:
    runs-on: ubuntu-latest
    steps:
      - name: Install and configure the Koyeb CLI
        uses: koyeb-community/koyeb-actions@v2
        with:
          api_token: "${{ secrets.KOYEB_API_TOKEN }}"

      - name: Cleanup Koyeb application
        uses: koyeb/action-git-deploy/cleanup@v1

In this example, the workflow listens for any branch or tag that is deleted using the '*' wildcard. When a delete event occurs, the cleanup job runs and uses the koyeb/action-git-deploy/cleanup action to remove the corresponding Koyeb service. Be sure to set KOYEB_API_TOKEN as a repository secret.