Use a GitHub Action to deploy to Northflank

GitHub Actions makes it easy to automate all your build, test, and deployment workflows. In this guide, we will show you how to deploy an image to Northflank with Github Actions using the Deploy to Northflank action. This approach makes it easy to integrate deploying to Northflank into your existing GitHub workflows.

This example builds an image and deploys it to an existing Northflank service or job. In the following sections, we will show you how to set up the prerequisites for this workflow.

name: Build Image and Deploy to Northflank

# Build and deploy the application everytime someone pushes to the "master" branch.
on:
   push:
      branches: ['master']

env:
   REGISTRY: ghcr.io
   IMAGE_NAME: ${{ github.repository }}

   PROJECT_ID: default-project
   SERVICE_ID: example-service
   CREDENTIALS_ID: github

jobs:
   build-and-deploy:
      runs-on: ubuntu-latest
      permissions:
         contents: read
         packages: write

      steps:
         # Step 1 - Checkout the repository containing our application's source code.
         - name: Checkout repository
           uses: actions/checkout@v3

         # Step 2 - Authenticate us with the container registry we intend to push a image to.
         - name: Log in to the Container registry
           uses: docker/login-action@f054a8b539a109f9f41c372932f1ae047eff08c9
           with:
              registry: ${{ env.REGISTRY }}
              username: ${{ github.actor }}
              password: ${{ secrets.GITHUB_TOKEN }}

         # Step 3 - Extract metadata we can feed into the following step.
         - name: Extract metadata (tags, labels) for Docker
           id: meta
           uses: docker/metadata-action@98669ae865ea3cffbcbaa878cf57c20bbf1c6c38
           with:
              images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}

         # Step 4 - Build the Docker image and push it to the container registry we previously authenticated with.
         - name: Build and push Docker image
           uses: docker/build-push-action@ad44023a93711e3deb337508980b4b5e9bcdc5dc
           with:
              context: .
              push: true
              tags: ${{ steps.meta.outputs.tags }}
              labels: ${{ steps.meta.outputs.labels }}

         # Step 5 - Deploy the image to an existing Northflank service or job. 
         - name: Deploy to Northflank
           uses: northflank/deploy-to-northflank@v1
           with:
              northflank-api-key: ${{ secrets.NORTHFLANK_API_KEY }}
              project-id: ${{ env.PROJECT_ID }}
              service-id: ${{ env.SERVICE_ID }}
              image-path: ${{ steps.meta.outputs.tags }}
              credentials-id: ${{ env.CREDENTIALS_ID }}

• For jobs, replace references in the workflow to a service's ID to a job's ID, e.g. replace SERVICE_ID with JOB_ID.

To use the Deploy to Northflank action, it needs a Northflank API key.

1. Create a new API token with the "Update Deployment" permission.

   • For more information on how to create an API token, check out our documentation.

2. Navigate to the settings tab of the GitHub repository containing your workflow, and select "Actions" under the "Secrets" collapsable section of the sidebar.

3. Create a new secret with the name NORTHFLANK_API_KEY and set the secret to the API key created in the previous step.

   

For the Deploy to Northflank action to deploy an image, we need to create a service or job it can deploy to.

1. Create a new deployment service with the following configuration:

   1. Under deployment, select Northflank and leave the linked build service blank.

      • Although our Docker image is not built on Northflank, the GitHub action will re-configure the service appropriately when it is run.

   2. Configure the service's environmental variables, networking, resources, etc. as appropriate for the application you intend to deploy.

   

2. Set the value of the PROJECT_ID in the env section of the workflow to the ID of the project you created the service in.

3. Set the value of the SERVICE_ID in the env section of the workflow to the ID of the service you created.

1. Create a new cron job or manual job with the following configuration:

   1. Under job source, select Northflank and leave the linked build service blank.

      • Although our Docker image is not built on Northflank, the GitHub action will re-configure the service appropriately when it is run.

   2. Configure the job's settings, environmental variables, resources, etc. as appropriate for the application you intend to deploy.

2. Replace references in the workflow to a service's ID to a job's ID, e.g. replace SERVICE_ID with JOB_ID.

3. Set the value of the PROJECT_ID in the env section of the workflow to the ID of the project you created the job in.

4. Set the value of the JOB_ID in the env section of the workflow to the ID of the job you created.

For Northflank to run the image, we need to save the container registry's credentials in the Northflank app:

1. Add a new registry in your account dashboard.

   • For more information on how to configure container registry credentials, check out our documentation.

2. Set the value of the CREDENTIALS_ID in the env section of the workflow to the ID of the registry you added.

To run the workflow, make some changes to your application and push them to the repository. Once the workflow is completed, you should see the change deployed to your Northflank service or job.

If you encounter any issues while following this guide we're happy to assist you with your deployment at support@northflank.com. At Northflank we also have dedicated support plans for business customers.