docs: add example with github deployments

[badsyntax]

Although not specific to the dokku workflow, it might be helpful to include examples of how to use GitHub deploys.

I recently set this up on my repo and find it somewhat useful.

Here's an example of the GitHub deploys:

I find it especially useful in pull requests. In my case i'm using the review-apps:create feature to create a staging deploy when I add a "staging" label to my PR.

In progress:

Complete:

[josegonzalez]

Should we add an if: success() here?

[badsyntax]

Steps will only run when previous steps are successful so no need to specify if: success(), but i'll add it to make it more explicit and easier to read 👍

[josegonzalez]

What are flash and ant-man?

[badsyntax]

It's totally weird when you first see it 😆

As GitHub deploys is still in beta/preview these media types are required to set certain properties.

From the docs:

The inactive state and the log_url, environment_url, and auto_inactive parameters are currently available for developers to preview. Please see the blog post for full details.
To access the API during the preview period, you must provide a custom media type in the Accept header:
application/vnd.github.ant-man-preview+json

And:

To access the new environment parameter, the two new values for the state parameter (in_progress and queued), and use auto_inactive on production deployments during the public beta period, you must provide the following custom media type in the Accept header:
application/vnd.github.flash-preview+json

[josegonzalez]

Can you turn this into appname.example.com?

[josegonzalez]

Is there a way to change the environment based on whether its a PR or not? Might be good to make this whole example something that uses review-apps when not master as well?

[badsyntax]

I'll see what I can do 👍

[badsyntax]

I've setup an example repo to play with the workflow for review apps, see badsyntax/dokku-github-actions-demo#4

The problem with using environments for review apps is you can only have one deployment per environment. So this needs some more thought. I'm still looking into this and I'll update this PR if/when I can find a solution for this.

[badsyntax]

The docs mention:

Running a workflow that references an environment that does not exist will create an environment with the referenced name.

So this could be the solution, although when i tried this without the environment existing, i was getting 404's, but I could have been missing something.

[badsyntax]

Another approach is to use 1 environment (eg review) and set auto_inactive to false to keep existing deploys active. https://docs.github.com/en/rest/reference/repos#inactive-deployments

I like this approach more than creating new environments "on the fly" as it means we can utilise the environment deploy rules.

[badsyntax]

I've made some good progress with this and GitHub Deploys are pretty awesome! We can use GitHub Deploys to request reviews before deployment, which is especially useful for review apps, as we might not want a deploy on every PR (as this open for abuse for public repos).

I'm getting close to updating this PR.

[rjocoleman]

Hello, the GH deployments API is out of preview and also is another action that handles creating and displaying GH deployments - for anyone looking here's an example:

---
name: 'deploy'

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

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

      - uses: chrnorm/deployment-action@v2
        name: Create GitHub deployment
        id: deployment
        with:
          token: '${{ github.token }}'
          environment-url: 'https://appname.dokku.me'
          environment: 'production'

      - 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 }}'

      - name: Update deployment status (success)
        if: success()
        uses: chrnorm/deployment-status@v2
        with:
          token: '${{ github.token }}'
          environment-url: '${{ steps.deployment.outputs.environment_url }}'
          deployment-id: '${{ steps.deployment.outputs.deployment_id }}'
          state: 'success'

      - name: Update deployment status (failure)
        if: failure()
        uses: chrnorm/deployment-status@v2
        with:
          token: '${{ github.token }}'
          environment-url: '${{ steps.deployment.outputs.environment_url }}'
          deployment-id: '${{ steps.deployment.outputs.deployment_id }}'
          state: 'failure'

Other than this dokku action, the third party actions in use are:

https://github.com/chrnorm/deployment-action
https://github.com/chrnorm/deployment-status