GitHub Actions

Use GitHub Actions to orchestrate Octopus from your CI pipeline for a seamless CI/CD workflow.

Integrating GitHub Actions with Octopus Deploy allows you to trigger events in Octopus (like creating a Release) based on events in GitHub (like pushing to main) for an effortless transition from CI to CD.

Octopus Deploy Actions

Octopus Deploy provides GitHub Actions which enable you to:

• Login to Octopus Deploy
• Install Octopus CLI
• Create a Release
• Deploy a Release
• Deploy a Tenanted Release
• Run a Runbook
• Push Build Information
• Create a Zip Package
• Create a NuGet Package
• Push Packages to Octopus Deploy
• Wait for/ watch an Execution Task

Getting started

Octopus Deploy GitHub Actions can be easily incorporated into your own GitHub Action workflows by including them as steps in your workflow YAML. Here is a simple GitHub Action workflow YAML to get you started.

Example workflow - Create and deploy a release

# .github/workflows/hello-octopus-deploy.yml
name: Hello Octopus Deploy

on:
  workflow_dispatch:

jobs:
  octopus-deployment:
    runs-on: ubuntu-latest

    permissions:
      id-token: write # Required by login action

    env:
      OCTOPUS_SPACE: 'Outer Space'
      # Supply the following values if not using the login action:
      # OCTOPUS_API_KEY: ${{ secrets.API_KEY  }}
      # OCTOPUS_URL: ${{ secrets.SERVER }}

    steps:
    - name: Checkout repository
      uses: actions/checkout@v3

    # Your own build steps go here!
    - name: Your build ✨
      run: echo "Your build steps!"

    # Action to Login to Octopus Deploy
    - name: Login to Octopus Deploy 🐙
      uses: OctopusDeploy/login@v1
      with: 
        server: ${{ secrets.SERVER }}
        service_account_id: a1a1a1a1-b2b2-c3c3-d4d4-e5e5e5e5e5e5
    
    # Action to Create a Release
    - name: Create a release in Octopus Deploy 🐙
      uses: OctopusDeploy/create-release-action@v3
      with:
        project: 'MyProject'
        release_number: '1.0.0'
        git_ref: ${{ github.ref }}
        git_commit: ${{ github.sha }}
    
    # Action to Deploy a Release
    - name: Deploy a release in Octopus Deploy 🐙
      uses: OctopusDeploy/deploy-release-action@v3
      with:
        project: 'MyProject'
        release_number: '1.0.0'
        environments: |
            Dev
            Test
        variables: |
            Flip: Bling
            Fizz: Buzz
        git_ref: ${{ github.ref }}
        git_commit: ${{ github.sha }}

✍️ Environment variables

📥 Inputs

Handling packages

To help you package your files for deployment, Octopus Deploy provides actions to Create a Zip Package or Create a NuGet Package.

Alternatively, you can Install the Octopus CLI and create packages using the pack command.

Once your packages are created, simply push them to the Octopus Server built-in repository using our Push Packages Octopus Action.

You can confirm that your packages have been successfully added by checking for them in your Space under ‘Packages’.

Here is a simple example of how to create, push and use a Zip package in a Release.

Example workflow - Working with packages

# .github/workflows/hello-octopus-packages.yml
name: Hello Octopus Packages

on:
  workflow_dispatch:

jobs:
  octopus-packages:
    runs-on: ubuntu-latest

    permissions:
      id-token: write # Required by login action

    env:
      OCTOPUS_SPACE: 'Outer Space'

    steps:
      - name: Checkout repository
        uses: actions/checkout@v3

      # Action to Login to Octopus Deploy
      - name: Login to Octopus Deploy 🐙
        uses: OctopusDeploy/login@v1
        with: 
          server: ${{ secrets.SERVER }}
          service_account_id: a1a1a1a1-b2b2-c3c3-d4d4-e5e5e5e5e5e5
      
      # Action to Create a Zip Package
      - name: Create a Zip package 🐙
        uses: OctopusDeploy/create-zip-package-action@v3
        with:
          package_id: 'HelloPackage'
          version: '1.0.0'
          output_folder: './packages/'
          base_path: './src/files-to-package/'
          files: |
            **/*.*
      
      # Action to Push Packages to Octopus Deploy
      - name: Push a package to Octopus Deploy 🐙
        uses: OctopusDeploy/push-package-action@v3
        with:
          packages: |
            packages/**/*.zip
      
      # Using your Package in a Release
      - name: Use the Package in a Release 🎉
        uses: OctopusDeploy/create-release-action@v3
        with:
          project: 'MyProject'
          release_number: '1.0.0'
          git_ref: ${{ github.ref }}
          git_commit: ${{ github.sha }}
          packages: |
            HelloPackage:1.0.0

📥 Additional inputs

Runners

Octopus Deploy GitHub Actions can be run on every available type of runner (Ubuntu Linux, Microsoft Windows, macOS, and Self-Hosted).

If your Octopus Server is not accessible over the internet, you can connect to it using a Self-Hosted runner.

Sequencing tasks

It can be useful to run multiple Octopus Deploy GitHub Actions in sequence as part of a larger workflow. To do this, simply include each Octopus Action as a step within a single job.

If you need to run sequential actions in separate jobs, you can also configure your jobs to run sequentially by defining prerequisite jobs.

Previous versions

Since the release of v3, Octopus Deploy GitHub Actions no longer need the Install Octopus CLI package to be installed before running. Each Octopus Action introduced before v3 provides a guide to migrating to v3.

Help us continuously improve

Please let us know if you have any feedback about this page.

Send feedback

Page updated on Friday, September 27, 2024