GitHub Deployments

bobheadxi/deployments is a GitHub Action for working painlessly with GitHub 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 lifecycles.

📢 This project is in need of additional maintainers - if you are interested in helping out please let me know!

• Configuration
  • step: start
  • step: finish
  • step: deactivate-env
  • step: delete-env
• Debugging
• Migrating to v1

A simple example:

on:
  push:
    branches:
    - main

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
    - name: start deployment
      uses: bobheadxi/deployments@v1
      id: deployment
      with:
        step: start
        token: ${{ secrets.GITHUB_TOKEN }}
        env: release

    - name: do my deploy
      # ...

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

You can also refer to other projects that also use this action - you can find more usages of this action on Sourcegraph, or check out the following examples:

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

Also feel free to chime in on the show and tell discussion to share your usages of this Action!

Check out this blog post for a bit of background on the origins of this project.

Configuration

The following inputs configuration options are for all steps:

| Variable | Default | Purpose | | ------------ | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | | step | | One of start, finish, deactivate-env, or delete-env | | token | ${{ github.token }} | provide your ${{ github.token }} or ${{ secrets.GITHUB_TOKEN }} for API access | | env | | identifier for environment to deploy to (e.g. staging, prod, main) | | repository | Current repository | target a specific repository for updates, e.g. owner/repo | | logs | URL to GitHub commit checks | URL of your deployment logs | | desc | GitHub-generated description | description for this deployment | | ref | github.ref | Specify a particular git ref to use, (e.g. ${{ github.head_ref }}) |

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

In addition to the core configuration, the following inputs are available:

| Variable | Default | Purpose | | --------------- | ------- | --------------------------------------------------------------------------------------------------- | | deployment_id | | Use an existing deployment instead of creating a new one (e.g. ${{ github.event.deployment.id }}) | | override | false | whether to mark existing deployments of this environment as inactive | | payload | | JSON-formatted dictionary with extra information about the deployment | | task | 'deploy' | change the task associated with this deployment, can be any string

The following outputs are available:

| Variable | Purpose | | --------------- | -------------------------------------- | | deployment_id | ID of created GitHub deployment | | status_id | ID of created GitHub deployment status | | env | name of configured environment |

<details> <summary>Simple Push Example</summary> <p>

on:
  push:
    branches:
    - main

jobs:
  deploy:
    steps:
    - name: start deployment
      uses: bobheadxi/deployments@v1
      id: deployment
      with:
        step: start
        env: release

    - name: do my deploy
      # ...

</p> </details> <br /> <details> <summary>Simple Pull Request Example</summary> <p>

on:
  pull_request:

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
    - name: start deployment
      uses: bobheadxi/deployments@v1
      id: deployment
      with:
        step: start
        env: integration

    - name: do my deploy
      # ...

</p> </details> <br />

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:

In addition to the core configuration, the following inputs are available:

| Variable | Default | Purpose | | --------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | status | | provide the current deployment job status ${{ job.status }} | | deployment_id | | identifier for deployment to update (see outputs of [step: start](#step-sta