Skip to content

README.md

Latest commit

 

History

History
206 lines (161 loc) · 12 KB

README.md

File metadata and controls

206 lines (161 loc) · 12 KB
Raw

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.