login

A GitHub action to login to your Octopus Deploy server.

After successful login, the GitHub Actions environment will be configured so that credentials do not need to be supplied to later Octopus actions (e.g. create-release-action) or the Octopus CLI.

This action supports two ways of logging in:

OpenID Connect (OIDC)

Support for OpenID Connect is currently being rolled out to Octopus Cloud and may not be available in your Octopus version just yet.

Using OpenID Connect (OIDC) is the recommended way to login to Octopus from GitHub Actions. It allows the granting of short-lived access tokens for a service account in Octopus that can be used during your GitHub Actions workflow run, without needing to provision or store an API key.

For more information about using OpenID Connect in GitHub Actions see about security hardening with OpenID Connect.

To login using OIDC:

• Create a service account in Octopus with the permissions required. Note that OIDC is only support for service accounts, not user accounts.
• Configure an OIDC identity for the service account that matches the GitHub Actions subject claim for your repository and workflow. See the Octopus OIDC documentation for more information.
  • See example subject claims for more information on the way that subject strings are generated by GitHub Actions.
• Copy the Service Account Id value from the Octopus service account. This will be a GUID.
• Configure your workflow job to have the id-token: write permissions. This allows the OctopusDeploy/login action to request an ID token from GitHub as part of the OIDC login process.
• Add the OctopusDeploy/login action to your workflow, specifying the server and service_account_id inputs.

Inputs

Name	Description
server	The URL of your Octopus server. This input is required.
service_account_id	The id of the service account you wish to login as. This input is required if using OIDC to login.

Outputs

Name	Description
server	The URL of your Octopus server that has been logged into. The environment variable OCTOPUS_URL will also be set with this value.
access_token	An access token that can be use to authenticate when making API requests. The environment variable OCTOPUS_ACCESS_TOKEN will also be set with this value.

Example

jobs:
  create_release_in_octopus:
    runs-on: ubuntu-latest
    name: Create a release in Octopus
    permissions:
      # You might need to add other permissions here like `contents: read` depending on what else your job needs to do
      id-token: write # This is required to obtain an ID token from GitHub Actions for the job
    steps:
      - name: Login to Octopus
        uses: OctopusDeploy/login@v1
        with:
          server: https://my.octopus.app
          service_account_id: 5be4ac10-2679-4041-a8b0-7b05b445e19e

      - name: Create a release in Octopus
        uses: OctopusDeploy/create-release-action@v3
        with:
          space: Default
          project: My Octopus Project

Support in other GitHub Actions

Using OIDC with other Octopus supplied GitHub Actions is supported in all v3 versions of actions that connect to Octopus Server, including:

• OctopusDeploy/await-task-action
• OctopusDeploy/create-release-action
• OctopusDeploy/deploy-release-action
• OctopusDeploy/deploy-release-tenanted-action
• OctopusDeploy/push-build-information-action
• OctopusDeploy/push-package-action
• OctopusDeploy/run-runbook-action

Using OIDC with the Octopus CLI is also supported from version 1.6.0 onwards. The CLI can be installed in a workflow using the OctopusDeploy/install-octopus-cli-action

API Key

To login using an API Key:

• Provision an API key in Octopus. See How to create an API key for more information. It is recommended that a service account is used instead of a user account.
• Add the OctopusDeploy/login action to your workflow, specifying the server and api_key inputs.

Inputs

Name	Description
server	The URL of your Octopus server. This input is required.
api_key	The API key you wish to login in with. It is strongly recommended to store this as a secret in GitHub Actions. This input is required if using API Key to login.

Outputs

Name	Description
server	The URL of your Octopus server that has been logged into. The environment variable OCTOPUS_URL will also be set with this value.
api_key	The API key that was used to login in with. The environment variable OCTOPUS_API_KEY will also be set with this value.

Example

jobs:
  create_release_in_octopus:
    runs-on: ubuntu-latest
    name: Create a release in Octopus
    steps:
      - name: Login to Octopus
        uses: OctopusDeploy/login@v1
        with:
          server: https://my.octopus.app
          api_key: ${{ secrets.OCTOPUS_API_KEY }}

      - name: Create a release in Octopus
        uses: OctopusDeploy/create-release-action@v3
        with:
          space: Default
          project: My Octopus Project