Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update docs to include codefresh login step #2543

Merged
merged 2 commits into from
Nov 4, 2024
Merged

Update docs to include codefresh login step #2543

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
f0e1c1f
Update docs to include codefresh login step
bec-callow-oct Oct 28, 2024
640416c
Document option use of API key
bec-callow-oct Oct 31, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
198 changes: 178 additions & 20 deletions src/pages/docs/packaging-applications/build-servers/codefresh-pipelines.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
layout: src/layouts/Default.astro
pubDate: 2024-09-19
modDate: 2024-09-19
modDate: 2024-10-31
title: Codefresh Pipelines
description: Codefresh pipelines can leverage the Octopus CLI to build, push, and create releases for Octopus Deploy.
navOrder: 50
Expand All @@ -16,6 +16,7 @@ Codefresh pipelines allow you to customize steps to create, deploy and promote r

Octopus Deploy has several custom pipeline steps available:

- [Login to Octopus](https://codefresh.io/steps/step/octopusdeploy-login)
- [Create a package](https://codefresh.io/steps/step/octopusdeploy-create-package)
- [Push a package](https://codefresh.io/steps/step/octopusdeploy-push-package)
- [Create a release](https://codefresh.io/steps/step/octopusdeploy-create-release)
Expand All @@ -31,15 +32,33 @@ When creating your first Codefresh Pipeline, the pipeline workflow can be define

The details of an Octopus instance are required to run all Octopus Codefresh steps:

| Variable name | Description|
| ------------- | ------- |
| `OCTOPUS_URL` | The Octopus Server URL you wish to run your steps on |
| `OCTOPUS_API_KEY` | The Octopus Deploy API Key required for authentication |
| `OCTOPUS_SPACE` | The Space to run steps on |
| Variable name | Description |
|------------------------|---------------------------------------------------------------------------------------------------------------------|
| `OCTOPUS_URL` | The Octopus Server URL you wish to run your steps on |
| `OCTOPUS_API_KEY` | The Octopus Deploy API Key required for authentication |
| `OCTOPUS_ACCESS_TOKEN` | This value is set by the **octopusdeploy-login** step, and should be passed as an argument to all following steps |
| `AUDIENCE` | The Octopus Deploy audience or service account ID required for authentication |
| `OCTOPUS_SPACE` | The Space to run steps on |

### Authentication to Octopus server

The following steps require Octopus server authentication:

- [Push a package](https://codefresh.io/steps/step/octopusdeploy-push-package)
- [Create a release](https://codefresh.io/steps/step/octopusdeploy-create-release)
- [Deploy a release](https://codefresh.io/steps/step/octopusdeploy-deploy-release)
- [Deploy a tenanted release](https://codefresh.io/steps/step/octopusdeploy%2Fdeploy-release-tenanted)
- [Run a runbook](https://codefresh.io/steps/step/octopusdeploy-run-runbook)
- [Push build information](https://codefresh.io/steps/step/octopusdeploy-push-build-information)

There are two options for authentication. You can:

1. Use the [Login to Octopus step](https://codefresh.io/steps/step/octopusdeploy-login) and provide `OCTOPUS_ACCESS_TOKEN` as an argument for each step.
2. Skip the login step and provide an `OCTOPUS_API_KEY` as an argument for each step.

## Codefresh variables

It is recommended to use Codefresh variables to set the `OCTOPUS_URL` and an encrypted variable to set the `OCTOPUS_API_KEY`. This way, you can simply insert the variable for all octopus deploy steps in your workflow.
It is recommended to use Codefresh variables to set the `OCTOPUS_URL` and an encrypted variable to set the `AUDIENCE`. This way, you can simply insert the variable for all octopus deploy steps in your workflow.

These can be set by clicking **Add Variable** from the **Variable** menu of your Codefresh Pipeline.

Expand Down Expand Up @@ -103,9 +122,114 @@ steps:
...
```

# Example Pipeline build
# Example Pipeline builds

The following examples demonstrate a Codefresh Pipeline build of an application sourced from Github.

## When using the Login step

To build and deploy this application, you'll need the following steps:

- Clone the source code
- Obtain OIDC token (available from the [Codefresh Marketplace](https://codefresh.io/steps/))
- Login
- Create a package
- Push package to Octopus Deploy instance
- Create a release for an existing project (get started with the basics of [setting up a project](/docs/projects/setting-up-projects))
- Deploy

Below is an example Codefresh Pipeline workflow which includes these steps:

<details>
<summary>Click here to view the entire example build YAML</summary>

```yaml
version: "1.0"

stages:
- "build and push"
- "deploy"

steps:
clone:
title: "Cloning repository"
type: "git-clone"
stage: "build and push"
repo: <<YOUR REPO URL>>
revision: "main"
working_directory: "/codefresh/volume"
credentials:
username: ${{GITHUB_USERNAME}}
password: ${{GITHUB_PASSWORD}}

obtain_id_token:
title: Obtain ID Token
type: obtain-oidc-id-token
stage: "Login"

login:
type: octopusdeploy-login
title: Login
stage: "login"
arguments:
# ID_TOKEN is set as an environment variable by the obtain_id_token step
ID_TOKEN: '${{ID_TOKEN}}'
OCTOPUS_URL: "https://example.octopustest.app/"
OCTOPUS_SERVICE_ACCOUNT_ID: <<YOUR_AUDIENCE_VALUE>>

create-package:
title: "Create package"
type: octopusdeploy-create-package
stage: "build and push"
arguments:
ID: "Hello"
VERSION: "1.0.0-${{CF_BUILD_ID}}"
BASE_PATH: "/codefresh/volume"
OUT_FOLDER: "/codefresh/volume"

push-package:
title: "Push package"
type: octopusdeploy-push-package
stage: "build and push"
arguments:
# OCTOPUS_ACCESS_TOKEN is set as an environment variable by the octopusdeploy-login step
OCTOPUS_ACCESS_TOKEN: ${{OCTOPUS_ACCESS_TOKEN}}
OCTOPUS_URL: ${{OCTOPUS_URL}}
OCTOPUS_SPACE: "Spaces-42"
PACKAGES:
- "/codefresh/volume/Hello.1.0.0-${{CF_BUILD_ID}}.zip"
OVERWRITE_MODE: 'overwrite'

The following example demonstrates a Codefresh Pipeline build of an application sourced from Github.
create-release:
type: octopusdeploy-create-release
title: "Create release"
stage: "deploy"
arguments:
OCTOPUS_ACCESS_TOKEN: ${{OCTOPUS_ACCESS_TOKEN}}
OCTOPUS_URL: ${{OCTOPUS_URL}}
OCTOPUS_SPACE: "Spaces-42"
PROJECT: "Demo Project"
RELEASE_NUMBER: "1.0.0-${{CF_BUILD_ID}}"
PACKAGES:
- "Hello:1.0.0-${{CF_BUILD_ID}}"
RELEASE_NOTES: This is a release note

deploy:
type: octopusdeploy-deploy-release
title: "Deploy release"
stage: "deploy"
arguments:
OCTOPUS_ACCESS_TOKEN: ${{OCTOPUS_ACCESS_TOKEN}}
OCTOPUS_URL: ${{OCTOPUS_URL}}
OCTOPUS_SPACE: "Spaces-42"
PROJECT: "Demo Project"
RELEASE_NUMBER: "1.0.0-${{CF_BUILD_ID}}"
ENVIRONMENTS:
- "Development"
```
</details>

## When using an API key

To build and deploy this application, you'll need the following steps:

Expand Down Expand Up @@ -196,6 +320,23 @@ Octopus Deploy steps and examples are available from the [Codefresh Marketplace]

Each step includes one or two examples to help with setting up a workflow. Basic examples include only required arguments, and complex examples include both required and optional arguments.

## Login to Octopus
The **octopusdeploy-login** step authenticates to Octopus via OIDC, so your Octopus server needs a [service account with OIDC enabled](/docs/octopus-rest-api/openid-connect/other-issuers).
To allow connections from Codefresh, the service account's OIDC identity should have **Issuer** `https://oidc.codefresh.io` and a **Subject** matching the [Codefresh subject claim for your preferred pipeline trigger](https://codefresh.io/docs/docs/integrations/oidc-pipelines/#codefresh-trigger-types-for-subject-claims).

The **octopusdeploy-login** step requires an `ID_TOKEN`, which can be generated by running the Codefresh **obtain-oidc-id-token** Marketplace step. This step sets the token as an environment variable which can be passed into the Octopus login step as an argument. See the [Codefresh OIDC documentation](https://codefresh.io/docs/docs/integrations/oidc-pipelines/) for further details.

```yaml
login:
type: octopusdeploy-login
arguments:
ID_TOKEN: '${{ID_TOKEN}}'
OCTOPUS_URL: '${{OCTOPUS_URL}}'
OCTOPUS_SERVICE_ACCOUNT_ID: '${{OCTOPUS_SERVICE_ACCOUNT_ID}}'

```
This step returns `OCTOPUS_ACCESS_TOKEN` as a string, which should be passed into subsequent steps to authenticate.

## Package artifacts
Create zip packages of your deployment artifacts by using the **octopusdeploy-create-package** step. Specify the files to include in each package, the location of those files and the details of the artifact to create. The following step packages all `.txt` files in the `/codefresh/volume` directory into the zip file `/codefresh/volume/Fresh.1.0.0.zip`:

Expand All @@ -220,7 +361,7 @@ Once the artifacts are packaged, use the **octopusdeploy-push-package** step to
push-package:
type: octopusdeploy-push-package
arguments:
OCTOPUS_API_KEY: '${{OCTOPUS_API_KEY}}'
OCTOPUS_ACCESS_TOKEN: '${{OCTOPUS_ACCESS_TOKEN}}' # Option to replace with OCTOPUS_API_KEY: ${{OCTOPUS_API_KEY}}
OCTOPUS_URL: '${{OCTOPUS_URL}}'
OCTOPUS_SPACE: "Default"
PACKAGES:
Expand All @@ -236,7 +377,7 @@ To create a release, use the **octopusdeploy-create-release** step. Provide the
create-release:
type: octopusdeploy-create-release
arguments:
OCTOPUS_API_KEY: '${{OCTOPUS_API_KEY}}'
OCTOPUS_ACCESS_TOKEN: '${{OCTOPUS_ACCESS_TOKEN}}' # Option to replace with OCTOPUS_API_KEY: ${{OCTOPUS_API_KEY}}
OCTOPUS_URL: '${{OCTOPUS_URL}}'
OCTOPUS_SPACE: "Default"
PROJECT: "Project Name"
Expand All @@ -248,7 +389,7 @@ Optional arguments help to customize the creation of the release. You can specif
create-release:
type: octopusdeploy-create-release
arguments:
OCTOPUS_API_KEY: '${{OCTOPUS_API_KEY}}'
OCTOPUS_ACCESS_TOKEN: '${{OCTOPUS_ACCESS_TOKEN}}' # Option to replace with OCTOPUS_API_KEY: ${{OCTOPUS_API_KEY}}
OCTOPUS_URL: '${{OCTOPUS_URL}}'
OCTOPUS_SPACE: "Default"
PROJECT: "Project Name"
Expand All @@ -269,7 +410,7 @@ To deploy a release, use the **octopusdeploy-deploy-release** step. Provide deta
deploy-release:
type: octopusdeploy-deploy-release
arguments:
OCTOPUS_API_KEY: '${{OCTOPUS_API_KEY}}'
OCTOPUS_ACCESS_TOKEN: '${{OCTOPUS_ACCESS_TOKEN}}' # Option to replace with OCTOPUS_API_KEY: ${{OCTOPUS_API_KEY}}
OCTOPUS_URL: '${{OCTOPUS_URL}}'
OCTOPUS_SPACE: "Default"
PROJECT: "Project Name"
Expand All @@ -284,7 +425,7 @@ Additionally, you can provide optional arguments to specify guided failure mode
deploy-release:
type: octopusdeploy-deploy-release
arguments:
OCTOPUS_API_KEY: '${{OCTOPUS_API_KEY}}'
OCTOPUS_ACCESS_TOKEN: '${{OCTOPUS_ACCESS_TOKEN}}' # Option to replace with OCTOPUS_API_KEY: ${{OCTOPUS_API_KEY}}
OCTOPUS_URL: '${{OCTOPUS_URL}}'
OCTOPUS_SPACE: "Default"
PROJECT: "Project Name"
Expand All @@ -305,7 +446,7 @@ To deploy a tenanted release, use the **octopusdeploy-deploy-release-tenanted**
deploy-release-tenanted:
type: octopusdeploy-deploy-release-tenanted
arguments:
OCTOPUS_API_KEY: '${{OCTOPUS_API_KEY}}'
OCTOPUS_ACCESS_TOKEN: '${{OCTOPUS_ACCESS_TOKEN}}' # Option to replace with OCTOPUS_API_KEY: ${{OCTOPUS_API_KEY}}
OCTOPUS_URL: '${{OCTOPUS_URL}}'
OCTOPUS_SPACE: Spaces 1
PROJECT: Project Name
Expand All @@ -321,7 +462,7 @@ Optional arguments help to customize the deployment of the release. You can spec
deploy-release-tenanted:
type: octopusdeploy-deploy-release-tenanted
arguments:
OCTOPUS_API_KEY: '${{OCTOPUS_API_KEY}}'
OCTOPUS_ACCESS_TOKEN: '${{OCTOPUS_ACCESS_TOKEN}}' # Option to replace with OCTOPUS_API_KEY: ${{OCTOPUS_API_KEY}}
OCTOPUS_URL: '${{OCTOPUS_URL}}'
OCTOPUS_SPACE: Spaces 1
PROJECT: Project Name
Expand All @@ -345,7 +486,7 @@ To run a runbook, use the **octopusdeploy-run-runbook** step. Provide the name o
run-runbook:
type: octopusdeploy-run-runbook
arguments:
OCTOPUS_API_KEY: '${{OCTOPUS_API_KEY}}'
OCTOPUS_ACCESS_TOKEN: '${{OCTOPUS_ACCESS_TOKEN}}' # Option to replace with OCTOPUS_API_KEY: ${{OCTOPUS_API_KEY}}
OCTOPUS_URL: '${{OCTOPUS_URL}}'
OCTOPUS_SPACE: Spaces 1
PROJECT: Project Name
Expand All @@ -361,7 +502,7 @@ Optional arguments include variables to use within the runbook, the option to ru
run-runbook:
type: octopusdeploy-run-runbook
arguments:
OCTOPUS_API_KEY: '${{OCTOPUS_API_KEY}}'
OCTOPUS_ACCESS_TOKEN: '${{OCTOPUS_ACCESS_TOKEN}}' # Option to replace with OCTOPUS_API_KEY: ${{OCTOPUS_API_KEY}}
OCTOPUS_URL: '${{OCTOPUS_URL}}'
OCTOPUS_SPACE: Spaces 1
PROJECT: Project Name
Expand Down Expand Up @@ -391,7 +532,7 @@ By default, the step will fail if build information already exists, but this can
push-build-information:
type: octopusdeploy-push-build-information
arguments:
OCTOPUS_API_KEY: '${{OCTOPUS_API_KEY}}'
OCTOPUS_ACCESS_TOKEN: '${{OCTOPUS_ACCESS_TOKEN}}' # Option to replace with OCTOPUS_API_KEY: ${{OCTOPUS_API_KEY}}
OCTOPUS_URL: '${{OCTOPUS_URL}}'
OCTOPUS_SPACE: Spaces 1
PACKAGE_IDS:
Expand Down Expand Up @@ -432,9 +573,25 @@ Codefresh provides inbuilt error handling for all steps. Retry of failed steps i
```yaml
version: "1.0"
stages:
- "Login"
- "Deploy project"

steps:
obtain_id_token:
title: Obtain ID Token
type: obtain-oidc-id-token
stage: "Login"

login:
type: octopusdeploy-login
title: Login
stage: "login"
arguments:
# ID_TOKEN is set as an environment variable by the obtain_id_token step
ID_TOKEN: '${{ID_TOKEN}}'
OCTOPUS_URL: "https://example.octopustest.app/"
OCTOPUS_SERVICE_ACCOUNT_ID: <<YOUR_AUDIENCE_VALUE>>

deploy:
type: octopusdeploy-deploy-release
stage: "Deploy project"
Expand All @@ -443,7 +600,8 @@ steps:
delay: 5
exponentialFactor: 2
arguments:
OCTOPUS_API_KEY: <<YOUR_API_KEY>>
# OCTOPUS_ACCESS_TOKEN is set as an environment variable by the octopusdeploy/login step
OCTOPUS_ACCESS_TOKEN: '${{OCTOPUS_ACCESS_TOKEN}}'
OCTOPUS_URL: "https://example.octopustest.app/"
OCTOPUS_SPACE: "Spaces-1"
PROJECT: "Create Release Test"
Expand Down
Loading