Skip to content
You're viewing an older version of this GitHub Action. Do you want to see the latest version instead?
bookmark

GitHub Action

GitHub Deployments

v0.6.1

GitHub Deployments

bookmark

GitHub Deployments

GitHub action for working painlessly with deployment statuses

Installation

Copy and paste the following snippet into your .yml file.

 
              
- name: GitHub Deployments

              
  uses: bobheadxi/deployments@v0.6.1
Learn more about this action in bobheadxi/deployments

Choose a version

GitHub Deployments View Action

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.

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. You can also refer to other projects that also use this action:

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":

deploy 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:

deploy finished

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:

env 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.

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