GitHub is a popular git-based source-control platform.
GitHub Actions is GitHub’s cloud-based continuous integration server.
The GitHub-hosted runners require your Octopus Server to be accessible over the Internet. Otherwise you must self-host your runners.
Integrating with GitHub Actions
Octopus Deploy has several custom GitHub Actions available:
All of the Actions are compatible with following runner types:
- Windows
- MacOS
- Linux
- Self-Hosted Runners
GitHub Actions secrets
You can use encrypted secrets in your workflow (available from the Settings ➜ Secrets menu of your GitHub repository), which is a great place to store sensitive information such as your Octopus Deploy API keys (which is not something you should store in your source control).
For example:
Variable name | Description |
---|---|
OCTOPUS_SERVER_URL | The Octopus Server URL you wish to push the final package to |
OCTOPUS_SERVER_API_KEY | The Octopus Deploy API Key required for authentication |
OCTOPUS_SERVER_SPACE | The Space to push packages to |
GitHub Actions configuration
When you create your first GitHub Action for your repository, GitHub stores the actions as workflows in the .github/workflows
folder in your repository. You need to modify those files to run the build, pack, and/or push package commands.
Triggering a build
A build within GitHub Actions can be triggered in a few different ways such as:
- Pull requests on a branch
- Push
- Schedule
- On-demand
All build triggers are defined in the on
section of the GitHub Actions YAML file.
Pull requests
To configure your build to be triggered from a pull request on a branch, add a pull_request
element to the on
section of the YAML file. Branches are listed in an array so you can define more than one. In this example, the build can be triggered from a pull request on the main
branch:
name: MyBuild
on:
pull_request:
branches: [ main ]
Push
A common method for triggering a build is to initiate the build whenever something is pushed to the repository. Adding push
will trigger a build whenever a push is made to the repository:
name: MyBuild
on:
push:
Schedule
A GitHub Actions build can also be triggered on a schedule. Schedules are defined using the unix cron
format. The following example configures the build to execute at 7AM every day:
name: MyBuild
on:
schedule:
- cron: "0 07 * * *"
If your repo has been inactive for over 60 days, cron jobs will stop building.
On-demand
It’s also possible to manually trigger a GitHub Actions build on-demand. To configure manual builds, add workflow_dispatch
to your build file:
name: MyBuild
on:
workflow_dispatch:
Adding workflow_dispatch
will enable the Run workflow
button that will allow manual runs.
Building with GitHub Actions
GitHub Actions builds consist of jobs which in turn consist of steps. By default, GitHub Actions jobs will run in parallel with each other while the steps within a job are executed sequentially. It’s possible to configure jobs to run sequentially using the jobs.<job_id>.need
keyword. See the GitHub documentation on Using jobs in a workflow for more details.
Before defining the steps for your job, you must first tell GitHub Actions what type of runner to use. The GitHub documentation explains the different types to choose from.
name: MyBuild
on:
pull_request:
branches: [ main ]
schedule:
- cron: "0 07 * * *"
workflow_dispatch:
jobs:
build:
runs-on: ubuntu-latest
Example .NET Core build
The following example demonstrates a GitHub Actions build of our example application, OctoPetShop. This application is written in .NET Core and consists of four components:
- OctopusSamples.OctoPetShop.Database - Database updates using DBUp
- OctopusSamples.OctoPetShop.Web - Web front end
- OctopusSamples.OctoPetShop.ProductService - Product service API
- OctopusSamples.OctoPetShop.ShoppingCartService - Shopping cart service API
To build this application, you’ll need the following steps:
- Checkout the source code
- Configure the runner with the appropriate version of .NET core
- Restore any NuGet packages required by the solution
- Build the solution
- Create folders to store published/compiled artifacts
- Publish each project to their respective artifact folders
Below is an example GitHub Actions workflow which includes these steps:
name: MyBuild
on:
pull_request:
branches: [ main ]
schedule:
- cron: "0 07 * * *"
workflow_dispatch:
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- name: Set Version
run: echo "PACKAGE_VERSION=$(date +'%Y.%m.%d').$GITHUB_RUN_NUMBER" >> $GITHUB_ENV
- name: Setup .NET Core
uses: actions/setup-dotnet@v1
with:
dotnet-version: 6.0.x
- name: Install dependencies
run: dotnet restore
- name: Build
run: dotnet build --configuration Release --no-restore
- name: Create artifacts folder
run: |
mkdir "$GITHUB_WORKSPACE/artifacts"
mkdir "$GITHUB_WORKSPACE/artifacts/OctopusSamples.OctoPetShop.Database"
mkdir "$GITHUB_WORKSPACE/artifacts/OctopusSamples.OctoPetShop.Web"
mkdir "$GITHUB_WORKSPACE/artifacts/OctopusSamples.OctoPetShop.ProductService"
mkdir "$GITHUB_WORKSPACE/artifacts/OctopusSamples.OctoPetShop.ShoppingCartService"
- name: Publish OctoPetShopDatabase
run: dotnet publish OctopusSamples.OctoPetShop.Database/OctopusSamples.OctoPetShop.Database.csproj --configuration Release --no-restore --output "$GITHUB_WORKSPACE/artifacts/OctopusSamples.OctoPetShop.Database"
- name: Publish OctoPetShopWeb
run: dotnet publish OctopusSamples.OctoPetShop.Web/OctopusSamples.OctoPetShop.Web.csproj --configuration Release --no-restore --output "$GITHUB_WORKSPACE/artifacts/OctopusSamples.OctoPetShop.Web"
- name: Publish OctoPetShopProductService
run: dotnet publish OctopusSamples.OctoPetShop.ProductService/OctopusSamples.OctoPetShop.ProductService.csproj --configuration Release --no-restore --output "$GITHUB_WORKSPACE/artifacts/OctopusSamples.OctoPetShop.ProductService"
- name: Publish OctoPetShopShoppingCartService
run: dotnet publish OctopusSamples.OctoPetShop.ShoppingCartService/OctopusSamples.OctoPetShop.ShoppingCartService.csproj --configuration Release --no-restore --output "$GITHUB_WORKSPACE/artifacts/OctopusSamples.OctoPetshop.ShoppingCartService"
Packaging artifacts
To package your artifacts for deployment, configure your build to use the OctopusDeploy/install-octopus-cli-action
developed by Octopus Deploy by adding the following step (previous steps excluded for brevity):
- name: Install Octopus CLI
uses: OctopusDeploy/install-octopus-cli-action@v1
with:
version: latest
Adding this Action allows your build to use the commands from the Octopus command line interface (CLI). Using the pack command, you can package your artifacts for deployment. The following example packages the OctoPetShop components built above:
- name: Install Octopus CLI
uses: OctopusDeploy/install-octopus-cli-action@v1
with:
version: latest
- name: Package OctoPetShopDatabase
run: |
octo pack --id="OctoPetShop.Database" --format="Zip" --version="$PACKAGE_VERSION" --basePath="$GITHUB_WORKSPACE/artifacts/OctopusSamples.OctoPetShop.Database" --outFolder="$GITHUB_WORKSPACE/artifacts"
- name: Package OctoPetShopWeb
run: |
octo pack --id="OctoPetShop.Web" --format="Zip" --version="$PACKAGE_VERSION" --basePath="$GITHUB_WORKSPACE/artifacts/OctopusSamples.OctoPetShop.Web" --outFolder="$GITHUB_WORKSPACE/artifacts"
- name: Package OctoPetShopProductService
run: |
octo pack --id="OctoPetShop.ProductService" --format="Zip" --version="$PACKAGE_VERSION" --basePath="$GITHUB_WORKSPACE/artifacts/OctopusSamples.OctoPetShop.ProductService" --outFolder="$GITHUB_WORKSPACE/artifacts"
- name: Package OctoPetShopShoppingCartService
run: |
octo pack --id="OctoPetShop.ShoppingCartService" --format="Zip" --version="$PACKAGE_VERSION" --basePath="$GITHUB_WORKSPACE/artifacts/OctopusSamples.OctoPetshop.ShoppingCartService" --outFolder="$GITHUB_WORKSPACE/artifacts"
Pushing artifacts to Octopus Server
Once the artifacts are packaged, use the OctopusDeploy/push-package-action Action to push the packages to the Octopus Server built-in repository. The following example pushes the packages created from the previous pack
operation:
- name: Push OctoPetShop packages
uses: OctopusDeploy/push-package-action@v1
with:
api_key: ${{ secrets.OCTOPUS_SERVER_API_KEY }}
server: ${{ secrets.OCTOPUS_SERVER_URL }}
packages: "artifacts/OctoPetShop.Database.${{ env.PACKAGE_VERSION }}.zip,artifacts/OctoPetShop.Web.${{ env.PACKAGE_VERSION }}.zip,artifacts/OctoPetShop.ProductService.${{ env.PACKAGE_VERSION }}.zip,artifacts/OctoPetShop.ShoppingCartService.${{ env.PACKAGE_VERSION }}.zip"
space: ${{ secrets.OCTOPUS_SERVER_SPACE }}
Creating a release
To create a release, use the OctopusDeploy/create-release-action. This action also contains the ability to deploy the newly created release. Use either the progress
or wait_for_deployment
options to have the build wait for the deployment to complete and report success or failure. Using progress
will display messages from Octopus itself whereas wait_for_deployment
will simply wait for Octopus to report success or failure:
- name: Create and deploy release
uses: OctopusDeploy/create-release-action@v1
with:
api_key: ${{ secrets.OCTOPUS_SERVER_API_KEY }}
server: ${{ secrets.OCTOPUS_SERVER_URL }}
space: ${{ secrets.OCTOPUS_SERVER_SPACE }}
project: "Octo Pet Shop"
deploy_to: "Development"
progress: true
The variable PACKAGE_VERSION must be referenced like ${{ env.PACKAGE_VERSION }} for both push-package-action and create-release-action
Complete build example
The previous sections displayed only the portions relevant to the topic being discussed. The entire build YAML for the Octo Pet Shop is located below:
Click here to view the entire example build YAML
name: MyBuild
on:
pull_request:
branches: [ main ]
schedule:
- cron: "0 07 * * *"
workflow_dispatch:
logLevel:
description: 'Log level'
required: true
default: 'warning'
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- name: Set Version
run: echo "PACKAGE_VERSION=$(date +'%Y.%m.%d').$GITHUB_RUN_NUMBER" >> $GITHUB_ENV
- name: Setup .NET Core
uses: actions/setup-dotnet@v1
with:
dotnet-version: 2.2.207
- name: Install dependencies
run: dotnet restore
- name: Build
run: dotnet build --configuration Release --no-restore
- name: Test
run: dotnet test --no-restore --verbosity normal
- name: Create artifacts folder
run: |
mkdir "$GITHUB_WORKSPACE/artifacts"
mkdir "$GITHUB_WORKSPACE/artifacts/OctopusSamples.OctoPetShop.Database"
mkdir "$GITHUB_WORKSPACE/artifacts/OctopusSamples.OctoPetShop.Web"
mkdir "$GITHUB_WORKSPACE/artifacts/OctopusSamples.OctoPetShop.ProductService"
mkdir "$GITHUB_WORKSPACE/artifacts/OctopusSamples.OctoPetShop.ShoppingCartService"
- name: Publish OctoPetShopDatabase
run: dotnet publish OctopusSamples.OctoPetShop.Database/OctopusSamples.OctoPetShop.Database.csproj --configuration Release --no-restore --output "$GITHUB_WORKSPACE/artifacts/OctopusSamples.OctoPetShop.Database"
- name: Publish OctoPetShopWeb
run: dotnet publish OctopusSamples.OctoPetShop.Web/OctopusSamples.OctoPetShop.Web.csproj --configuration Release --no-restore --output "$GITHUB_WORKSPACE/artifacts/OctopusSamples.OctoPetShop.Web"
- name: Publish OctoPetShopProductService
run: dotnet publish OctopusSamples.OctoPetShop.ProductService/OctopusSamples.OctoPetShop.ProductService.csproj --configuration Release --no-restore --output "$GITHUB_WORKSPACE/artifacts/OctopusSamples.OctoPetShop.ProductService"
- name: Publish OctoPetShopShoppingCartService
run: dotnet publish OctopusSamples.OctoPetShop.ShoppingCartService/OctopusSamples.OctoPetShop.ShoppingCartService.csproj --configuration Release --no-restore --output "$GITHUB_WORKSPACE/artifacts/OctopusSamples.OctoPetshop.ShoppingCartService"
- name: Install Octopus CLI
uses: OctopusDeploy/install-octopus-cli-action@v1
with:
version: latest
- name: Package OctoPetShopDatabase
run: |
octo pack --id="OctoPetShop.Database" --format="Zip" --version="$PACKAGE_VERSION" --basePath="$GITHUB_WORKSPACE/artifacts/OctopusSamples.OctoPetShop.Database" --outFolder="$GITHUB_WORKSPACE/artifacts"
- name: Package OctoPetShopWeb
run: |
octo pack --id="OctoPetShop.Web" --format="Zip" --version="$PACKAGE_VERSION" --basePath="$GITHUB_WORKSPACE/artifacts/OctopusSamples.OctoPetShop.Web" --outFolder="$GITHUB_WORKSPACE/artifacts"
- name: Package OctoPetShopProductService
run: |
octo pack --id="OctoPetShop.ProductService" --format="Zip" --version="$PACKAGE_VERSION" --basePath="$GITHUB_WORKSPACE/artifacts/OctopusSamples.OctoPetShop.ProductService" --outFolder="$GITHUB_WORKSPACE/artifacts"
- name: Package OctoPetShopShoppingCartService
run: |
octo pack --id="OctoPetShop.ShoppingCartService" --format="Zip" --version="$PACKAGE_VERSION" --basePath="$GITHUB_WORKSPACE/artifacts/OctopusSamples.OctoPetshop.ShoppingCartService" --outFolder="$GITHUB_WORKSPACE/artifacts"
- name: Push OctoPetShop packages
uses: OctopusDeploy/push-package-action@v1
with:
api_key: ${{ secrets.OCTOPUS_SERVER_API_KEY }}
server: ${{ secrets.OCTOPUS_SERVER_URL }}
packages: "artifacts/OctoPetShop.Database.${{ env.PACKAGE_VERSION }}.zip,artifacts/OctoPetShop.Web.${{ env.PACKAGE_VERSION }}.zip,artifacts/OctoPetShop.ProductService.${{ env.PACKAGE_VERSION }}.zip,artifacts/OctoPetShop.ShoppingCartService.${{ env.PACKAGE_VERSION }}.zip"
space: ${{ secrets.OCTOPUS_SERVER_SPACE }}
- name: Create and deploy release
uses: OctopusDeploy/create-release-action@v1
with:
api_key: ${{ secrets.OCTOPUS_SERVER_API_KEY }}
server: ${{ secrets.OCTOPUS_SERVER_URL }}
space: ${{ secrets.OCTOPUS_SERVER_SPACE }}
project: "Octo Pet Shop"
deploy_to: "Development"
progress: true
Run a runbook
In addition to common build steps, we also have an action that can Run a Runbook.
- name: Run a runbook in Octopus Deploy
uses: OctopusDeploy/run-runbook-action@1.0.1
with:
api_key: ${{ secrets.OCTOPUS_SERVER_API_KEY }}
environments: 'Development'
project: 'Octo Pet Shop'
runbook: 'Restart IIS App pool'
server: ${{ secrets.OCTOPUS_SERVER_URL }}
space: ${{ secrets.OCTOPUS_SERVER_SPACE }}
show_progress: 'true'
Push Build Information
Build information contains a link to the build which produced the package, details of the source commits related to the build, and issue references parsed from the commit messages.
Build information is generated and pushed to Octopus with the
OctopusDeploy/push-build-information-action
step:
- name: Generate Octopus Deploy build information
uses: OctopusDeploy/push-build-information-action@v1
env:
OCTOPUS_API_KEY: ${{ secrets.OCTOPUS_API_TOKEN }}
OCTOPUS_HOST: ${{ secrets.OCTOPUS_SERVER_URL }}
with:
version: ${{ env.PACKAGE_VERSION }}
packages: OctoPetShopWeb
overwrite_mode: OverwriteExisting
Commits will only be included when a workflow is triggered by a push event.
Example GitHub Actions Repo:
View a working GitHub Actions examples on our samples GitHub repository.
GitHub Action Integrations v3
GitHub Action Integrations v3 no longer requires the Octo CLI to function. This new native approach brings many benefits to the table, including but not limited too:
- Smaller actions
- Faster runtimes
- Performance benefits through the Executions API
Migration Guides
Migrations guides can be found on each GitHub Action Integration Repo.
New GitHub Actions
The following GitHub actions have been created in collaboration with Github Action v3.
Deploy Release
Incorporate the following actions in your workflow to deploy a release in Octopus Deploy using an API key, a target instance (i.e. server), and a project:
env:
steps:
# ...
- name: Deploy a release in Octopus Deploy 🐙
uses: OctopusDeploy/deploy-release-action@v3
env:
OCTOPUS_API_KEY: ${{ secrets.API_KEY }}
OCTOPUS_URL: ${{ secrets.SERVER }}
OCTOPUS_SPACE: 'Outer Space'
with:
project: 'MyProject'
release_number: '1.0.0'
environments: |
Dev
Test
variables: |
Foo: Bar
Fizz: Buzz
Deploy Release Tenanted
env:
steps:
# ...
- name: Deploy a release in Octopus Deploy 🐙
uses: OctopusDeploy/deploy-release-tenanted-action@v3
env:
OCTOPUS_API_KEY: ${{ secrets.API_KEY }}
OCTOPUS_URL: ${{ secrets.SERVER }}
OCTOPUS_SPACE: 'Outer Space'
with:
project: 'MyProject'
release_number: '1.0.0'
environment: 'Dev'
tenants: |
'Some Tenant A'
'Some Tenant B'
tenant_tags: |
'setA/someTagB'
'setC/someTagD'
variables: |
'Foo: Bar'
'Fizz: Buzz'
Await Task
Incorporate the following actions in your workflow to wait for a task to complete in Octopus Deploy:
env:
steps:
# ...
- name: Await task in Octopus Deploy 🐙
uses: OctopusDeploy/await-task-action@v3
env:
OCTOPUS_API_KEY: ${{ secrets.API_KEY }}
OCTOPUS_URL: ${{ secrets.SERVER }}
OCTOPUS_SPACE: 'Outer Space'
with:
server_task_id: ${{ fromJson(steps.some_previous_deployment_step.outputs.server_tasks)[0].serverTaskId }}
Create Nuget Package
Create NuGet package(s) to push to Octopus Deploy.
steps:
- uses: actions/checkout@v3
# create a NuGet package from files in the "reports" folder; create package in "packaging" folder
- name: Create a NuGet package 🐙
uses: OctopusDeploy/create-nuget-package-action@v3
with:
package_id: 'DemoPackage'
version: '1.0.0'
output_folder: 'packaging'
base_path: reports
files: |
**/*.*
nuspec_description: package description
nuspec_authors: |
author 1
author 2
nuspec_release_notes: |
This is a multiline
release note
Create Zip Package
Create Zip package(s) to push to Octopus Deploy.
steps:
- uses: actions/checkout@v3
# create a Zip package from files in the "reports" folder; create package in "packaging" folder
- name: Create a Zip package 🐙
uses: OctopusDeploy/create-zip-package-action@v3
with:
package_id: 'DemoPackage'
version: '1.0.0'
output_folder: './packaging'
base_path: reports
files: |
**/*.*
Install Octopus CLI Action v3
Although the CLI is not required for GitHub Actions v3, the install Octopus CLI Action v3 will now install the new Octopus CLI.
If you require the use of the original Octo CLI, you can use OctopusDeploy/install-octopus-cli-action@v1
.
Help us continuously improve
Please let us know if you have any feedback about this page.
Page updated on Thursday, June 13, 2024