Repository: dokku/github-action
Branch: master
Commit: b705ed643fea
Files: 18
Total size: 19.6 KB

Directory structure:
gitextract_beyc28cw/

├── .github/
│   ├── dependabot.yaml
│   ├── linters/
│   │   ├── .markdown-lint.yaml
│   │   └── .yamllint.yaml
│   └── workflows/
│       ├── build.yaml
│       └── lint.yaml
├── Dockerfile
├── LICENSE
├── README.md
├── action.yaml
└── example-workflows/
    ├── build-and-deploy.yaml
    ├── cancel-previous-runs.yaml
    ├── custom-deploy-branch.yaml
    ├── force-push.yaml
    ├── review-app/
    │   └── ci-pre-deploy
    ├── review-app.yaml
    ├── simple.yaml
    ├── specify-ssh-host-key.yaml
    └── verbose-logging.yaml

================================================
FILE CONTENTS
================================================

================================================
FILE: .github/dependabot.yaml
================================================
---
version: 2
updates:
  - package-ecosystem: "docker"
    directory: "/"
    schedule:
      interval: "daily"
  - package-ecosystem: "github-actions"
    directory: "/"
    schedule:
      interval: daily
    open-pull-requests-limit: 10
  - package-ecosystem: "github-actions"
    directory: "/example-workflows"
    schedule:
      interval: daily
    open-pull-requests-limit: 10


================================================
FILE: .github/linters/.markdown-lint.yaml
================================================
---
default: true

# Line length
# https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#md013
MD013: false


================================================
FILE: .github/linters/.yamllint.yaml
================================================
---
extends: default

rules:
  line-length: disable


================================================
FILE: .github/workflows/build.yaml
================================================
---
name: build

# yamllint disable-line rule:truthy
on:
  pull_request:
    branches:
      - '*'
  push:
    branches:
      - 'master'
jobs:
  docker:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v6

      - name: Docker meta
        id: meta
        uses: docker/metadata-action@v6
        with:
          images: |
            dokku/github-action
          tags: |
            type=semver,pattern={{version}}
            type=semver,pattern={{major}}.{{minor}}
            type=semver,pattern={{major}}
            type=sha

      - name: Set up QEMU
        uses: docker/setup-qemu-action@v4
      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v4

      - name: Login to DockerHub
        if: ${{ github.event_name != 'pull_request' }}
        uses: docker/login-action@v4
        with:
          username: ${{ secrets.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}

      - name: Build and push
        uses: docker/build-push-action@v7
        with:
          context: .
          platforms: linux/amd64,linux/arm64
          push: false
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}


================================================
FILE: .github/workflows/lint.yaml
================================================
---
name: "lint"

# yamllint disable-line rule:truthy
on:
  pull_request:
    branches:
      - "*"
  push:
    branches:
      - "master"

jobs:
  hadolint:
    name: hadolint
    runs-on: ubuntu-24.04
    steps:
      - name: Clone
        uses: actions/checkout@v6
      - name: Run hadolint
        uses: brpaz/hadolint-action@c27bd9edc1e95eed30474db8f295ff5807ebca14
        # v1.1.0 => eb9b96be611b84830aa1babacfb7070ecd2a8b1b

  markdown-lint:
    name: markdown-lint
    runs-on: ubuntu-24.04
    steps:
      - name: Clone
        uses: actions/checkout@v6
      - name: Run markdown-lint
        uses: avto-dev/markdown-lint@04d43ee9191307b50935a753da3b775ab695eceb
        # v1.4.0 => 6e6d4393411fbaae3c3aeee5661ba84a0352ed3b
        with:
          config: ".github/linters/.markdown-lint.yaml"
          args: "./README.md"

  yamllint:
    name: yamllint
    runs-on: ubuntu-24.04
    steps:
      - name: Clone
        uses: actions/checkout@v6
      - name: Run yamllint
        uses: ibiqlik/action-yamllint@2576378a8e339169678f9939646ee3ee325e845c
        # v3.0.0 => b2aeacc1b7eeb8c23e84bba320d04fb5d6a323ee
        with:
          config_file: ".github/linters/.yamllint.yaml"


================================================
FILE: Dockerfile
================================================
FROM dokku/ci-docker-image:0.17.1


================================================
FILE: LICENSE
================================================
MIT License

Copyright (c) 2020 Olivier Brassard
Copyright (c) 2020 Jose Diaz-Gonzalez

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.


================================================
FILE: README.md
================================================
# dokku github-action

Official Github Action for deploying apps to a Dokku installation

## Requirements

Please note that this action is compatible with `dokku >= 0.11.6`.

## Inputs

- `branch`: (_optional_) The branch to deploy when pushing to Dokku. Useful when a [custom deploy branch](https://dokku.com/docs/deployment/methods/git/#changing-the-deploy-branch) is set on Dokku.
  - default: `master`
  - example value: `main`
- `ci_branch_name`: (_optional_) The branch name that triggered the deploy. Automatically detected from `GITHUB_REF`.
  - example value: `develop`
- `ci_commit`: (_optional_) The commit sha that will be pushed. Automatically detected from `GITHUB_SHA`.
  - example value: `0aa00d8dd7c971c121e3d1e471d0a35e1daf8abe`
- `command`: (_optional_) The command to run for the action.
  - default: `deploy`
  - valid values:
    - `deploy`
    - `review-apps:create`: Used to create a review app - via `dokku apps:clone` - based on the `appname` configured in the `git_remote_url`. If the review app already exists, this action will not recreate the app. In both cases, the current commit will be pushed to the review app.
    - `review-apps:destroy`: Destroys an existing review app.
- `deploy_docker_image`:  (_optional_) A docker image to deploy via `git:from-image`.
  - example value: `dokku/test-app:1`
- `deploy_user_name`:  (_optional_) A username to use when deploying a docker image
- `deploy_user_email`:  (_optional_) The email to use when deploying a docker image.
- `git_push_flags`: (_optional_) A string containing a set of flags to set on push. This may be used to enable force pushes, or trigger verbose log output from git.
  - example value: `--force -vvv`
- `git_remote_url`: (**required**) The dokku app's git repository url in SSH format.
  - example value: `ssh://dokku@dokku.myhost.ca:22/appname`
- `review_app_name`: (_optional_) The name of the review app to create or destroy. Computed as `review-$APPNAME-$BRANCH_NAME` if not specified, where:

  ```text
  $APPNAME: The parsed app name from the `git_remote_url`
  $BRANCH_NAME: The inflected git branch name
  ```

  - example value: `review-appname`
- `ssh_host_key`: (_optional_) The results of running `ssh-keyscan -t rsa $HOST`. The github-action will otherwise generate this on the fly via `ssh-keyscan`.
  - example value:

    ```text
    # dokku.com:22 SSH-2.0-OpenSSH_8.2p1 Ubuntu-4ubuntu0.1
    dokku.com ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQCvS+lK38EEMdHGb...
    ```

- `ssh_private_key`: (**required**) A private ssh key that has push access to the Dokku instance.
  - tip: It is recommended to use [Encrypted Secrets](https://docs.github.com/en/free-pro-team@latest/actions/reference/encrypted-secrets) to store sensitive information such as SSH Keys.
  - example value:

    ```text
    -----BEGIN OPENSSH PRIVATE KEY-----
    MIIEogIBAAKCAQEAjLdCs9kQkimyfOSa8IfXf4gmexWWv6o/IcjmfC6YD9LEC4He
    qPPZtAKoonmd86k8jbrSbNZ/4OBelbYO0pmED90xyFRLlzLr/99ZcBtilQ33MNAh
    ...
    SvhOFcCPizxFeuuJGYQhNlxVBWPj1Jl6ni6rBoHmbBhZCPCnhmenlBPVJcnUczyy
    zrrvVLniH+UTjreQkhbFVqLPnL44+LIo30/oQJPISLxMYmZnuwudPN6O6ubyb8MK
    -----END OPENSSH PRIVATE KEY-----
    ```

- `ssh_passphrase`: (_optional_) Passphrase to use when interacting with an SSH key that has a passphrase
  - example value: `password`

- `trace`: (_optional_) Allows users to debug what the action is performing by enabling shell trace mode
  - example value: `1`

## Examples

All examples below are functionally complete and can be copy-pasted into a `.github/workflows/deploy.yaml` file, with some minor caveats:

- The `git_remote_url` should be changed to match the server and app.
- An [Encrypted Secret](https://docs.github.com/en/free-pro-team@latest/actions/reference/encrypted-secrets) should be set on the Github repository with the name `SSH_PRIVATE_KEY` containing the contents of a private ssh key that has been added to the Dokku installation via the `dokku ssh-keys:add` command.
- As pushing a git repository from a shallow clone does not work, all repository checkous should use a `fetch-depth` of `0`. All examples below have this option set correctly.

For simplicity, each example is standalone, but may be combined as necessary to create the desired effect.

- [Simple Example](/example-workflows/simple.yaml): Deploys a codebase on push or merge to master.
- [Build in CI and Deploy an image](/example-workflows/build-and-deploy.yaml): Builds a docker image in CI, pushes the image to the remote Docker Hub repository, and then notifies Dokku to deploy the built image.
- [Cancel previous runs on new push](/example-workflows/cancel-previous-runs.yaml): This workflow is particularly useful when triggered by new pushes, and utilizes a third-party action.
- [Avoid SSH Host Keyscan](/example-workflows/specify-ssh-host-key.yaml): By default, this action will scan the host for it's SSH host key and use that value directly. This may not be desirable for security compliance reasons.

  The `SSH_HOST_KEY` value can be retrieved by calling `ssh-keyscan -t rsa $HOST`, where `$HOST` is the Dokku server's hostname.
- [Specify a custom deploy branch](/example-workflows/custom-deploy-branch.yaml): Certain Dokku installations may use custom deploy branches other than `master`. In the following example, we push to the `develop` branch.
- [Verbose Push Logging](/example-workflows/verbose-logging.yaml): Verbose client-side logging may be enabled with this method, as well as trace mode for all shell command output. Note that this does not enable trace mode on the remote deploy, and simply tells the `git` client to enable verbose log output.
- [Force Pushing](/example-workflows/force-push.yaml): If the remote app has been previously pushed manually from a location other than CI, it may be necessary to enable force pushing to avoid git errors.
- [Review Apps](/example-workflows/review-app.yaml): Handles creation and deletion of review apps through use of `dokku apps:clone` and `dokku apps:destroy`. Review apps are a great way to allow folks to preview pull request changes before they get merged to production.
  - Placing a shell script at `bin/ci-pre-deploy` can be used to reconfigure the app, as shown in [this example](/example-workflows/review-app/ci-pre-deploy).


================================================
FILE: action.yaml
================================================
---
name: "Dokku"
description: "Official Github Action for deploying apps to a Dokku installation"
author: "Dokku"
branding:
  icon: "upload-cloud"
  color: "blue"
inputs:
  branch:
    description: "The branch to deploy when pushing to Dokku (default: master)"
    required: false
    default: "master"
  ci_branch_name:
    description: "The command to run for the action (default: detected from GITHUB_REF)"
    required: false
    default: ""
  ci_commit:
    description: "The commit sha that will be pushed (default: detected from GITHUB_SHA)"
    required: false
    default: ""
  command:
    description: "The command to run for the action (default: deploy)"
    required: false
    default: "deploy"
  deploy_docker_image:
    description: "A docker image to deploy via `git:from-image`"
    required: false
    default: ""
  deploy_user_name:
    description: "A username to use when deploying a docker image"
    required: false
    default: ""
  deploy_user_email:
    description: "The email to use when deploying a docker image"
    required: false
    default: ""
  git_push_flags:
    description: "A string containing a set of flags to set on push"
    required: false
    default: ""
  git_remote_url:
    description: "The dokku app's git repository url (in SSH format)"
    required: true
  review_app_name:
    description: "The name of the review app to create or destroy"
    required: false
    default: ""
  ssh_host_key:
    description: "The results of running `ssh-keyscan -t rsa $HOST`"
    required: false
    default: ""
  ssh_private_key:
    description: "A private SSH key that has push access to your Dokku instance"
    required: true
  ssh_passphrase:
    description: "Passphrase to use when interacting with an SSH key that has a passphrase"
    required: false
    default: ""
  trace:
    description: "Allows users to debug what the action is performing by enabling shell trace mode"
    required: false
    default: ""
runs:
  using: "docker"
  image: "Dockerfile"
  entrypoint: "/bin/dokku-deploy"
  post-entrypoint: "/bin/dokku-unlock"
  post-if: cancelled()
  env:
    BRANCH: ${{ inputs.branch }}
    CI_BRANCH_NAME: ${{ inputs.ci_branch_name }}
    CI_COMMIT: ${{ inputs.ci_commit }}
    COMMAND: ${{ inputs.command }}
    DEPLOY_DOCKER_IMAGE: ${{ inputs.deploy_docker_image }}
    DEPLOY_USER_NAME: ${{ inputs.deploy_user_name }}
    DEPLOY_USER_EMAIL: ${{ inputs.deploy_user_email }}
    GIT_PUSH_FLAGS: ${{ inputs.git_push_flags }}
    GIT_REMOTE_URL: ${{ inputs.git_remote_url }}
    REVIEW_APP_NAME: ${{ inputs.review_app_name }}
    SSH_HOST_KEY: ${{ inputs.ssh_host_key }}
    SSH_PRIVATE_KEY: ${{ inputs.ssh_private_key }}
    SSH_PASSPHRASE: ${{ inputs.ssh_passphrase }}
    TRACE: ${{ inputs.trace }}


================================================
FILE: example-workflows/build-and-deploy.yaml
================================================
---
name: 'deploy'

# yamllint disable-line rule:truthy
on:
  push:
    branches:
      - master

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Cloning repo
        uses: actions/checkout@v6
        with:
          fetch-depth: 0

      - name: Set up qemu
        uses: docker/setup-qemu-action@v4

      - name: Set up docker buildx
        uses: docker/setup-buildx-action@v4

      - name: Login to docker hub
        uses: docker/login-action@v4
        with:
          username: ${{ secrets.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}

      - name: Build and push
        uses: docker/build-push-action@v7
        with:
          push: true
          tags: ${{ github.repository }}:${{ github.sha }}

      - name: Push to dokku
        uses: dokku/github-action@master
        with:
          git_remote_url: 'ssh://dokku@dokku.me:22/appname'
          ssh_private_key: ${{ secrets.SSH_PRIVATE_KEY }}
          deploy_docker_image: ${{ github.repository }}:${{ github.sha }}


================================================
FILE: example-workflows/cancel-previous-runs.yaml
================================================
---
name: 'deploy'

# yamllint disable-line rule:truthy
on:
  push:
    branches:
      - master

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      # third-party action that cancels previous runs
      - name: Cancel Previous Runs
        uses: styfle/cancel-workflow-action@0.13.1
        with:
          access_token: ${{ github.token }}

      - name: Cloning repo
        uses: actions/checkout@v6
        with:
          fetch-depth: 0

      - name: Push to dokku
        uses: dokku/github-action@master
        with:
          git_remote_url: 'ssh://dokku@dokku.me:22/appname'
          ssh_private_key: ${{ secrets.SSH_PRIVATE_KEY }}


================================================
FILE: example-workflows/custom-deploy-branch.yaml
================================================
---
name: 'deploy'

# yamllint disable-line rule:truthy
on:
  push:
    branches:
      - master

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Cloning repo
        uses: actions/checkout@v6
        with:
          fetch-depth: 0

      - name: Push to dokku
        uses: dokku/github-action@master
        with:
          # specify the `main` branch as the remote branch to push to
          branch: 'main'
          git_remote_url: 'ssh://dokku@dokku.me:22/appname'
          ssh_private_key: ${{ secrets.SSH_PRIVATE_KEY }}


================================================
FILE: example-workflows/force-push.yaml
================================================
---
name: 'deploy'

# yamllint disable-line rule:truthy
on:
  push:
    branches:
      - master

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Cloning repo
        uses: actions/checkout@v6
        with:
          fetch-depth: 0

      - name: Push to dokku
        uses: dokku/github-action@master
        with:
          # specify `--force` as a flag for git pushes
          git_push_flags: '--force'
          git_remote_url: 'ssh://dokku@dokku.me:22/appname'
          ssh_private_key: ${{ secrets.SSH_PRIVATE_KEY }}


================================================
FILE: example-workflows/review-app/ci-pre-deploy
================================================
#!/bin/sh -l
if [ "$IS_REVIEW_APP" = "true" ]; then
  ssh "$SSH_REMOTE" -- config:set "$APP_NAME" "DOMAIN=$APP_NAME.dokku.me"
  echo "configured the review app domain"
fi


================================================
FILE: example-workflows/review-app.yaml
================================================
---
name: 'deploy'

# yamllint disable-line rule:truthy
on:
  # onl run this workflow on pull request events
  pull_request

jobs:
  create_review_app:
    runs-on: ubuntu-latest
    # only run when a pull request is opened
    if: github.event_name == 'pull_request' && github.event.action == 'opened'
    steps:
      - name: Cloning repo
        uses: actions/checkout@v6
        with:
          fetch-depth: 0

      - name: Create and push the review app
        uses: dokku/github-action@master
        with:
          # create a review app
          command: review-apps:create
          git_remote_url: 'ssh://dokku@dokku.me:22/appname'
          # specify a name for the review app
          review_app_name: review-appname-${{ github.event.pull_request.number }}
          ssh_private_key: ${{ secrets.SSH_PRIVATE_KEY }}


  deploy_review_app:
    runs-on: ubuntu-latest
    # only run when a pull request is not opened or closed
    if: github.event_name == 'pull_request' && github.event.action != 'opened' && github.event.action != 'closed'
    steps:
      - name: Cloning repo
        uses: actions/checkout@v6
        with:
          fetch-depth: 0

      - name: Push to dokku
        uses: dokku/github-action@master
        with:
          # create a review app
          git_remote_url: 'ssh://dokku@dokku.me:22/appname'
          # specify a name for the review app
          review_app_name: review-appname-${{ github.event.pull_request.number }}
          ssh_private_key: ${{ secrets.SSH_PRIVATE_KEY }}

  destroy_review_app:
    runs-on: ubuntu-latest
    # only run when a pull request is closed
    if: github.event_name == 'pull_request' && github.event.action == 'closed'
    steps:
      # only needed if you have destroy hooks
      - name: Cloning repo
        uses: actions/checkout@v6

      - name: Destroy the review app
        uses: dokku/github-action@master
        with:
          # destroy a review app
          command: review-apps:destroy
          git_remote_url: 'ssh://dokku@dokku.me:22/appname'
          # specify a name for the review app
          review_app_name: review-appname-${{ github.event.pull_request.number }}
          ssh_private_key: ${{ secrets.SSH_PRIVATE_KEY }}


================================================
FILE: example-workflows/simple.yaml
================================================
---
name: 'deploy'

# yamllint disable-line rule:truthy
on:
  push:
    branches:
      - master

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Cloning repo
        uses: actions/checkout@v6
        with:
          fetch-depth: 0

      - name: Push to dokku
        uses: dokku/github-action@master
        with:
          git_remote_url: 'ssh://dokku@dokku.me:22/appname'
          ssh_private_key: ${{ secrets.SSH_PRIVATE_KEY }}


================================================
FILE: example-workflows/specify-ssh-host-key.yaml
================================================
---
name: 'deploy'

# yamllint disable-line rule:truthy
on:
  push:
    branches:
      - master

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Cloning repo
        uses: actions/checkout@v6
        with:
          fetch-depth: 0

      - name: Push to dokku
        uses: dokku/github-action@master
        with:
          git_remote_url: 'ssh://dokku@dokku.me:22/appname'
          # specify an alternative ssh host key
          ssh_host_key: ${{ secrets.SSH_HOST_KEY }}
          ssh_private_key: ${{ secrets.SSH_PRIVATE_KEY }}


================================================
FILE: example-workflows/verbose-logging.yaml
================================================
---
name: 'deploy'

# yamllint disable-line rule:truthy
on:
  push:
    branches:
      - master

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Cloning repo
        uses: actions/checkout@v6
        with:
          fetch-depth: 0

      - name: Push to dokku
        uses: dokku/github-action@master
        # enable verbose ssh output
        env:
          GIT_SSH_COMMAND: 'ssh -vvv'
        with:
          # enable verbose git output
          git_push_flags: '-vvv'
          git_remote_url: 'ssh://dokku@dokku.me:22/appname'
          ssh_private_key: ${{ secrets.SSH_PRIVATE_KEY }}
          # enable shell trace mode
          trace: '1'