eafzali/deployments

🔖 GitHub Action for working painlessly with deployment statuses

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.6.2
      id: deployment
      with:
        step: start
        token: ${{ secrets.GITHUB_TOKEN }}
        env: release

    - name: do my deploy
      # ...

    - name: update deployment status
      uses: bobheadxi/deployments@v0.6.2
      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. You can also refer to other projects that also use this action:

• github/super-linter - GitHub's all-in-one linter Action
• mxcl/PromiseKit - promises for Swift and Objective-C
• mirumee/saleor - modular, high performance, headless e-commerce storefront
• sharetribe/sharetribe - marketplace software
• skylines-project/skylines - live tracking, flight database and competition web platform

You can find more usages of this action on Sourcegraph!

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 once the deployment starts
transient	false	Mark deployment as transient. Transient deployments are not automatically deactivated
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.6.2
      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.6.2
      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
auto_inactive	true	Mark previous non-transient deployments as inactive

Simple Example

# ...

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

    - name: do my deploy
      # ...

    - name: update deployment status
      uses: bobheadxi/deployments@v0.6.2
      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.6.2
      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.

If you run into an problems or have any questions, feel free to open an issue or discussion!