GitHub Deployments

bobheadxi/deployments is a GitHub Action for working painlessly with deployment statuses. Instead of exposing convoluted Action configuration that mirrors that of the GitHub API like some of the other available Actions do, this Action simply exposes a number of configurable, easy-to-use "steps" common to most deployment flows.

• Features
  • step: start
  • step: finish
  • step: deactivate-env
• Debugging

A simple example:

on:
  push:
    branches:
    - master

jobs:
  deploy:
    steps:
    - name: start deployment
      uses: bobheadxi/deployments@v0.4.3
      id: deployment
      with:
        step: start
        token: ${{ secrets.GITHUB_TOKEN }}
        env: release

    - name: do my deploy
      # ...

    - name: update deployment status
      uses: bobheadxi/deployments@v0.4.3
      if: always()
      with:
        step: finish
        token: ${{ secrets.GITHUB_TOKEN }}
        status: ${{ job.status }}
        deployment_id: ${{ steps.deployment.outputs.deployment_id }}

See this blog post for a bit of background and more practical example. Other usage examples in the wild:

• mirumee/saleor - a modular, high performance, headless e-commerce storefront
• skylines-project/skylines - live tracking, flight database and competition framework
• conveyal/analysis-ui - Conveyal's frontend for creating and analyzing transportation scenarios
• xt0rted/actions-cake-demo - demo project using GitHub Actions and Cake to build & deploy a .NET Core site to Azure App Services

Features

step: start

This is best used on the push: { branches: [ ... ] } event, but you can also have release: { types: [ published ] } trigger this event. start should be followed by whatever deployment tasks you want to do, and it creates and marks a deployment as "started":

The following inputs are available:

Variable	Default	Purpose
step		must be start for this step
token		provide your ${{ secrets.GITHUB_TOKEN }} for API access
logs	URL to GitHub commit checks	URL of your deployment logs
desc		description for this deployment
env		identifier for environment to deploy to (e.g. staging, prod, master)
no_override	true	toggle whether to mark existing deployments of this environment as inactive
deployment_id		Use an existing deployment instead of creating a new one (e.g. ${{ github.event.deployment.id }})
ref	github.ref	Specify a particular git ref to use, (e.g. ${{ github.head_ref }})

The following outputs are available:

Variable	Purpose
deployment_id	ID of created GitHub deployment
env	name of configured environment

Simple Push Example

on:
  push:
    branches:
    - master

jobs:
  deploy:
    steps:
    - name: start deployment
      uses: bobheadxi/deployments@v0.4.3
      id: deployment
      with:
        step: start
        token: ${{ secrets.GITHUB_TOKEN }}
        env: release

    - name: do my deploy
      # ...

Simple Pull Request Example

on:
  pull_request:

jobs:
  deploy:
    steps:
    - name: start deployment
      uses: bobheadxi/deployments@v0.4.3
      id: deployment
      with:
        step: start
        token: ${{ secrets.GITHUB_TOKEN }}
        env: integration
        ref: ${{ github.head_ref }}

    - name: do my deploy
      # ...

step: finish

This is best used after step: start and should follow whatever deployment tasks you want to do in the same workflow. finish marks an in-progress deployment as complete:

The following inputs are available:

Variable	Default	Purpose
step		must be finish for this step
token		provide your ${{ secrets.GITHUB_TOKEN }} for API access
logs	URL to GitHub commit checks	URL of your deployment logs
desc		description for this deployment
status		provide the current deployment job status ${{ job.status }}
deployment_id		identifier for deployment to update (see outputs of step: start)
env_url		URL to view deployed environment

Simple Example

# ...

jobs:
  deploy:
    steps:
    - name: start deployment
      # ... see previous example

    - name: do my deploy
      # ...

    - name: update deployment status
      uses: bobheadxi/deployments@v0.4.3
      if: always()
      with:
        step: finish
        token: ${{ secrets.GITHUB_TOKEN }}
        status: ${{ job.status }}
        deployment_id: ${{ steps.deployment.outputs.deployment_id }}

step: deactivate-env

This is best used on the pull_request: { types: [ closed ] } event, since GitHub does not seem to provide a event to detect when branches are deleted. This step can be used to automatically shut down deployments you create on pull requests and mark environments as destroyed:

The following inputs are available:

Variable	Default	Purpose
step		must be deactivate-env for this step
token		provide your ${{ secrets.GITHUB_TOKEN }} for API access
logs	URL to GitHub commit checks	URL of your deployment logs
desc		description for this deployment
env		identifier for environment to deploy to (e.g. staging, prod, master)

Simple Example

on:
  pull_request:
    types: [ closed ]

jobs:
  prune:
    steps:
    # see https://dev.to/bobheadxi/branch-previews-with-google-app-engine-and-github-actions-3pco
    - name: extract branch name
      id: get_branch
      shell: bash
      env:
        PR_HEAD: ${{ github.head_ref }}
      run: echo "##[set-output name=branch;]$(echo ${PR_HEAD#refs/heads/} | tr / -)"

    - name: do my deployment shutdown
      # ...

    - name: mark environment as deactivated
      uses: bobheadxi/deployments@v0.4.3
      with:
        step: deactivate-env
        token: ${{ secrets.GITHUB_TOKEN }}
        env: ${{ steps.get_branch.outputs.branch }}
        desc: Deployment was pruned

Debugging

The argument log_args: true can be provided to print arguments used by deployments.