Armory Docs – GitHub Integration Plugin for Spinnaker

Plugins: GitHub Integration Plugin for Spinnaker Overview

Mon, 01 Jan 0001 00:00:00 +0000

GitHub Integration Plugin features

The GitHub Integration Plugin provides the following GitHub integration features:

Trigger a GitHub Actions workflow from a Spinnaker pipeline using workflow_dispatch or repository_dispatch events.
Trigger a Spinnaker pipeline automatically when a GitHub workflow finishes successfully.
Trigger a Spinnaker pipeline when GitHub creates a new GitHub Deployment.
Monitor a GitHub workflow and finish pipeline execution based on the GitHub workflow result.
Update GitHub deployment status based on Spinnaker pipeline outcome.
View GitHub Action Logs in Spinnaker – there is no need to navigate to GitHub to view the logs.
Validate GitHub access based on configuration assigned to a GitHub App account.
Create GitHub commit statuses using Echo.
Use AuthZ for your GitHub Accounts.

The GitHub Integration plugin uses GitHub Apps to integrate with GitHub. GitHup Apps provide webhooks and narrow, specific permissions. You can install a GitHub App that gives the GitHub Integration plugin access to all the repos in your GitHub organization, or you can install a Github App that gives the GitHub Integration plugin access to specific repos. You can install as many GitHub Apps as your use case requires.

How the plugin works with GitHub

graph TD
Orca -->|Workflow Trigger| Igor
Gate --> |Trigger based on Deployment event|Echo
Igor -->|Trigger/Monitor triggered workflows| GitHub
Echo -->|Pipeline triggers|Orca
Orca -->|Pipeline notifications|Echo
GitHub --> |Deployment event| Gate
Echo --> |Notifications|GitHub

For example, the plugin processes a GitHub Deployment event like this:

sequenceDiagram
participant ghActions as "GitHub Workflow job"
participant gh as "GitHub"
participant gate as "Gate"
participant echo as "Echo"
participant orca as "Orca"
ghActions ->> gh: "Create Deployment"
gh ->> ghActions: "Deployment created"
gh ->> gate: "Deployment Event"
gate ->> echo: "Deployment trigger event"
echo ->> orca: "Trigger pipelines matching the Trigger event"
orca ->> gh: "Deployment status update: in_progress, success, failure, or error"

Compatibility matrix

Armory CD Version	Spinnaker Version	GitHub Integration Plugin Version
2.30.x	1.30.x	0.1.2

Installation paths

Armory CD
Armory Operator

Use a Kustomize patch to install the plugin.

Create a GitHub App and install it in your repo or organization.
Configure the plugin with your GitHub repo(s) and/or organization(s).
Install the plugin using the Armory Operator.

Instructions

Spinnaker
Spinnaker Operator

Use a Kustomize patch to install the plugin.

Create a GitHub App and install it in your repo.
Configure the plugin with your GitHub repo(s) and/or organization(s).
Install the plugin using the Spinnaker Operator.

Instructions

Spinnaker
Halyard

Use Spinnaker local config files to install the plugin.

Create a GitHub App and install it in your repo.
Configure the plugin with your GitHub repo(s) and/or organization(s).
Install the plugin in local config files and apply those changes using Halyard.

Instructions

Plugins: Get Started with the GitHub Integration Plugin

Mon, 01 Jan 0001 00:00:00 +0000

Armory CD
Armory Operator

Use a Kustomize patch to install the plugin.

Create a GitHub App and install it in your repo or organization.
Configure the plugin with your GitHub repo(s) and/or organization(s).
Install the plugin using the Armory Operator.

Instructions

Spinnaker
Spinnaker Operator

Use a Kustomize patch to install the plugin.

Create a GitHub App and install it in your repo.
Configure the plugin with your GitHub repo(s) and/or organization(s).
Install the plugin using the Spinnaker Operator.

Instructions

Spinnaker
Halyard

Use Spinnaker local config files to install the plugin.

Create a GitHub App and install it in your repo.
Configure the plugin with your GitHub repo(s) and/or organization(s).
Install the plugin in local config files and apply those changes using Halyard.

Instructions

Plugins: Enable and Configure AuthZ in the GitHub Integration Plugin

Mon, 01 Jan 0001 00:00:00 +0000

AuthZ plugin overview

This feature enables AuthZ support for GitHub App accounts and provides these features:

Compliance and Security

Authz for GitHub App accounts allows you to enforce access controls on a per-account basis, securing access to specific repositories and/or GitHub organizations to only authorized groups/teams.
Granular Control

Authz for GitHub App accounts provides granular control over who can perform actions within each account. This fine-grained permission control is crucial for maintaining a least privilege principle, where users have only the necessary access to perform their tasks, reducing the overall security surface.
Scalability

Authz for GitHub App accounts scales effectively as the number of accounts grows. This scalability is essential for organizations managing diverse and expanding infrastructure, ensuring that access controls remain manageable and effective.

Fiat is the Spinnaker microservice responsible for authorization (authz) for the other Spinnaker services. It is not enabled by default, so users are able to perform any action in Spinnaker. When enabled, Fiat checks the user’s permissions before allowing the action to proceed.

How this feature works

The GitHub Integration plugin supports Fiat authz for GitHub App accounts configured to determine whether a role or group can perform the following actions:

READ: A user can view the GitHub App account’s configuration and/or use it as a trigger source.
WRITE: A user can use the GitHub App account as the target account for the GitHub integration plugin stages.

sequenceDiagram
participant user as User
participant gate as Gate
participant orca as Orca
participant igor as Igor
participant fiat as Fiat
participant gh as GitHub
user ->> gate: Start execution for pipeline (includes plugin stage)
gate ->> orca: Submit execution for pipeline (includes plugin stage)
orca ->> igor: Submit the task operations of plugin stage
igor ->> fiat: Check hasPermissions
alt Unauthorized
fiat ->> igor: hasPermissions=false
igor ->> orca: Fail with Forbidden
orca ->> gate: TERMINAL
else Authorized
fiat ->> igor: hasPermissions=true
igor ->> orca: IN_PROGRESS
igor ->> gh: API calls
orca ->> gate: IN_PROGRESS
end

Before you begin

You are familiar with how Spinnaker’s AuthZ works.
You have read the GitHub Integration Plugin overview.
You have enabled Fiat in your Spinnaker or Armory CD instance integrated with an external identity provider (IDP).

How to enable AuthZ support

You can enable AuthZ support per GitHub App account by setting the permissions block in the github-integration-plugin.yml file. For example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37


github:
 plugin:
 accounts:
 - name: FirstAppRepo
 organization: company-public
 repository: first-app-repo
 defaultBranch: master
 githubAppId: 9753
 githubAppPrivateKey: encrypted:k8s!n:spin-secrets!k:github-app-9753-privatekey
 permissions:
 READ:
 - "read-only-role"
 - "dev-role"
 - "ops-role"
 EXECUTE:
 - "dev-role"
 - "ops-role"
 - name: SecondAppRepo
 organization: company-public
 repository: second-app-repo
 defaultBranch: main
 githubAppId: 9753
 githubAppPrivateKey: encrypted:k8s!n:spin-secrets!k:github-app-9753-privatekey
 permissions: []
 - name: CompanyPrivateOrgAllRepos
 organization: company-private
 orgWideInstallation: true
 includePublicRepositories: false
 defaultBranch: main
 githubAppId: 1357
 githubAppPrivateKey: encrypted:k8s!n:spin-secrets!k:github-app-1357-privatekey
 permissions:
 READ:
 - "read-only-role"
 - "ops-role"
 EXECUTE:
 - "ops-role"

Plugins: Enable GitHub Access Validation

Mon, 01 Jan 0001 00:00:00 +0000

Validate GitHub access

This feature validates GitHub access based on configuration assigned to a GitHub App account, providing an additional access control validation layer of a GitHub App account in Spinnaker against the defined GitHub Teams in the repository.

Using the impersonateGitHubTeam feature, you can validate and enforce GitHub App account access to repositories based on the GitHub team’s assigned configuration.

How this feature works

Before performing any action in a pipeline stage, the plugin validates that the GitHub teams configured using the impersonateGitHubTeam feature are assigned with one of the following roles in GitHub:

Admin: Full access to the repository
Write: Read and write access to the repository
Maintain: Read and write access to the repository, including managing issues and pull requests

If the GitHub team does not have appropriate access to the repository, the pipeline stage fails with an error message.

sequenceDiagram
participant user as User
participant gate as Gate
participant orca as Orca
participant igor as Igor
participant fiat as Fiat
participant gh as GitHub
user ->> gate: Start execution for pipeline (includes plugin stage)
gate ->> orca: Submit execution for pipeline (includes plugin stage)
orca ->> igor: Submit the task operations of plugin stage
igor ->> fiat: Check hasPermissions
alt Unauthorized
fiat ->> igor: hasPermissions=false
igor ->> orca: Fail with Forbidden
orca ->> gate: TERMINAL
else Authorized
fiat ->> igor: hasPermissions=true
igor ->> gh: Check permissions on Repository
gh ->> igor: Permissions
igor ->> igor: Evaluate Repo permissions
alt Unauthorized_onRepo
igor ->> orca: Fail with Forbidden on Repo Access
else Authorized_onRepo
orca ->> gate: IN_PROGRESS
end
end

How to enable

You enable the impersonateGitHubTeam feature per GitHub App account by setting the impersonateGitHubTeam block in the github-integration-plugin.yml file. For example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43


github:
 plugin:
 accounts:
 - name: FirstAppRepo
 organization: company-public
 repository: first-app-repo
 defaultBranch: master
 githubAppId: 9753
 githubAppPrivateKey: encrypted:k8s!n:spin-secrets!k:github-app-9753-privatekey
 permissions:
 READ:
 - "read-only-role"
 - "dev-role"
 - "ops-role"
 EXECUTE:
 - "dev-role"
 - "ops-role"
 impersonateGitHubTeam: []
 - name: SecondAppRepo
 organization: company-public
 repository: second-app-repo
 defaultBranch: main
 githubAppId: 9753
 githubAppPrivateKey: encrypted:k8s!n:spin-secrets!k:github-app-9753-privatekey
 permissions: []
 impersonateGitHubTeam:
 - "dev-github-team"
 - "ops-github-team"
 - name: CompanyPrivateOrgAllRepos
 organization: company-private
 orgWideInstallation: true
 includePublicRepositories: false
 defaultBranch: main
 githubAppId: 1357
 githubAppPrivateKey: encrypted:k8s!n:spin-secrets!k:github-app-1357-privatekey
 impersonateGitHubTeam:
 - "admin-github-team"
 permissions:
 READ:
 - "read-only-role"
 - "ops-role"
 EXECUTE:
 - "ops-role"

Plugins: Enable GitHub Commit Status Echo Notifications

Mon, 01 Jan 0001 00:00:00 +0000

Configure GitHub Commit Status Echo notifications

Echo is the microservice in Spinnaker which (among other functionalities) manages notifications for Spinnaker pipelines and stages.

Using the GitHub Integration plugin you can configure Echo to create GitHub Commit Statuses in a repository by authenticating using the GitHub App accounts configured in the plugin.

By using the GitHub Integration’s plugin GitHub Commit Status notifications, you can link the deployment pipeline statuses to GitHub status checks. This feature provides clear and immediate feedback to developers about the deployment pipeline status.

How this feature works

GitHub Integration plugin offers an enhanced Echo notification type which can be configured to send notifications for pipelines and/or stages statuses with custom context and description linking to the Spinnaker UI as a target URL.

How to enable

GitHub Commit Status notifications can be enabled per GitHub App account by enabling the feature in Echo and Deck services in the github-integration-plugin.yml file.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


spec:
 spinnakerConfig:
 profiles:
 spinnaker:
 github:
 plugin:
 github-status:
 enabled: true
 accounts: []
 deck:
 settings-local.js: |
 window.spinnakerSettings = {
 ... (content omitted for brevity)
 feature.githubIntegrationFlags = {
 githubStatus: true
 };
 ... (content omitted for brevity)
 } 

Migrating from Echo’s default implementation

Migrating from the default implementation to the GitHub Integration plugin’s implementation does not require any changes in your pipelines. The GitHub Integration plugin’s implementation is used automatically when the feature is enabled in Echo and Deck services and the default implementation is disabled. To ensure a smooth migration, follow these steps:

Disable the default implementation by disabling the github-status feature in Echo and Deck services

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


spec:
 spinnakerConfig:
 profiles:
 echo:
 github-status:
 enabled: false
 token: <PAT>
 endpoint: https://api.github.com
 deck:
 settings-local.js: |
 window.spinnakerSettings = {
 ... (content omitted for brevity)
 notifications.githubStatus.enabled = false;
 ... (content omitted for brevity)
 } 

Enable the GitHub Integration plugin. See the Get Started section for instructions.
Ensure that you have configured the appropriate GitHub App accounts for every GitHub organization that you want to send notifications to.
Verify that the Deck UI is showing the plugin’s Commit Status notification type in the notification settings for your pipelines and the Commit Statuses are being created in GitHub.

Plugins: Use the GitHub Integration Plugin

Mon, 01 Jan 0001 00:00:00 +0000

Before you begin

You should be familiar with GitHub workflows.

Trigger GitHub workflows from Spinnaker pipelines

Use the Github Integration Workflow Trigger Stage to trigger your GitHub workflow from your Spinnaker pipeline.

`workflow_dispatch` event

Configure the Github Integration Workflow Trigger Stage as in the following screenshot:

Github Account: (Required) Select the GitHub Account; this is one of the accounts you configured when you installed the plugin
Organization or User: (Required) The organization or username that should trigger the workflow
Project: (Required) Spinnaker project name
Workflow Name: (Required) The filename of your workflow
Git reference (branch or tag name): (Required) The branch or tag name that receives the workflow_dispatch event
Workflow Inputs: (Optional) Key/value pairs to pass to your GitHub workflow

`repository_dispatch` event

Configure the Github Integration Workflow Trigger Stage as in the following screenshot:

Github Account: (Required) Select the GitHub Account; this is one of the accounts you configured when you installed the plugin
Organization or User: (Required) The organization or username that should trigger the workflow
Project: (Required) Spinnaker project name
Event Type: (Required) The event type that should trigger the workflow
Client Payload Inputs: (Optional) Key/value pairs to pass to your GitHub workflow

Trigger Spinnaker pipelines from GitHub workflows

Workflow success trigger

To trigger a Spinnaker pipeline when a GitHub workflow finishes successfully, configure an automated trigger in your pipeline.

Type: (Required) Select GitHub Workflow Trigger
Github Account: (Required) Select the GitHub Account; this is one of the accounts you configured when you installed the plugin
Organization: (Required) Select the organization associated with the Github Account
Repository: (Required) Select the repository that contains the workflow
Workflow: (Required) Select the name of the workflow that Spinnaker should monitor
Branch: (Optional) If specified, only pushes to the branches that match this Java Regular Expression are triggered. Leave empty to trigger builds for every branch.

New deployment trigger

To trigger a Spinnaker pipeline when GitHub creates a new deployment, first create a deployment event webhook in GitHub. Armory strongly recommends you create a secret for the webhook.

Next, configure an automated trigger to process the deployment event from GitHub.

Type: (Required) Select GitHub Event Trigger
GitHub Account: (Required) Select the GitHub Account; this is one of the accounts you configured when you installed the plugin
Organization: (Required) Select the organization associated with the Github Account
Repository: (Required) Select the repository that contains the workflow
Secret: (Optional) Provide the name of the GitHub secret associated with the deployment workflow event webhook; the GitHub Integration Plugin does not process the request when the secrets do not match
Environment: (Optional) If specified, only deployment to the environment that matches this Java Regular Expression is triggered. Leave empty to trigger builds for every environment.

When the pipeline triggered by a deployment event finishes, Spinnaker automatically update the status of the GitHub deployment based on the pipeline’s outcome.

Fetch release information

You can use the GitHub Integration Releases Get Details stage to fetch the latest release information.

Github Account: (Required) Select the GitHub Account; this is one of the accounts you configured when you installed the plugin
Retrieve: (Required) Select Get Latest Release
Organization or User: (Required) The organization or username that should trigger the workflow
Project: (Required) Spinnaker project name

Fetch prerelease information

You can use the GitHub Integration Releases Get Details stage to fetch the latest prerelease information.

Github Account: (Required) Select the GitHub Account; this is one of the accounts you configured when you installed the plugin
Retrieve: (Required) Select Get Latest PreRelease
Organization or User: (Required) The organization or username that should trigger the workflow
Project: (Required) Spinnaker project name

Create GitHub Commit Status

The GitHub Commit Status pipeline stage allows you to create a GitHub Commit Status in a repository using the GitHub App accounts configured in the plugin without the need to configure a notification block in your pipelines and viewing the execution status of the stage in your pipeline’s execution details.

Configure the GitHub Integration Commit Status Stage as in the following screenshot:

GitHub Repo: (Required) The full repository name including the GitHub Org. For example myorg/mygithubrepo.
Commit Ref: (Required) The commit reference. Can be a commit SHA, branch name (heads/BRANCH_NAME), or tag name (tags/TAG_NAME).
Status: (Required) The state of the status. Can be one of: error, failure, pending, success.
Context: (Required) A string label to differentiate this status from the status of other systems. This field is case-insensitive.
Description: (Optional) A short description of the status.

Plugins: GiHub Integration Plugin Release Notes

Mon, 01 Jan 0001 00:00:00 +0000

v0.3.1 2023/11/21

Features

Added support for GitHub Commit Statuses notifications for pipelines and/or stages using Echo service. See Enable GitHub Commit Status Echo Notifications for more information.
Added GitHub Commit Status stage for pipelines. See Create GitHub Commit Status for more information.

v0.2.4 2023/11/21

Features

Added support for AuthZ for GitHub App accounts. See Enable and Configure AuthZ in the GitHub Integration Plugin for more information.
Added support for Validating GitHub App accounts access. See Enable GitHub Access Validation for more information.

v0.1.2 2023/11/01

Features

Added support for Manual (or Rerun) Execution of pipelines with trigger type GitHub Workflow Trigger.
Modified GitHub Workflow Trigger & GitHub Event Trigger Types to be enabled independently in Deck configuration.

v0.1.1 2023/10/18

Fixes

Fixed bug where the Igor fastForward admin endpoint didnt include the githubBuildMonitor monitor

v0.1.0 2023/10/12

Features

Initial release

Known issues

Armory.Header plugin conflict

Armory Continuous Deployment: The GitHub Integration plugin conflicts with the Armory.Header plugin’s default version installed in Armory Continuous Deployment 2.30.x.

Fix: Update your GitHub Integration plugin config to include the Armory.Header plugin v0.2.0

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


profiles:
 gate:
 spinnaker:
 extensibility:
 repositories:
 pluginRepository:
 url: https://raw.githubusercontent.com/armory-plugins/pluginRepository/master/repositories.json
 plugins:
 Armory.GitHubIntegration:
 enabled: true
 version: <version>
 Armory.ArmoryHeader:
 enabled: true
 version: 0.2.0
 deck-proxy:
 enabled: true
 plugins:
 Armory.GitHubIntegration:
 enabled: true
 version: <version>
 Armory.ArmoryHeader:
 enabled: true

Workflow Dispatch and Repository Dispatch run duration

The workflow run for the stages Workflow Dispatch and Repository Dispatch must have a minimum run duration of 30 seconds. If the duration is less than 30 seconds, both Spinnaker and Armory CDSH might fail to fetch the workflow details, causing the run to fail with a timeout error.

Armory Docs – GitHub Integration Plugin for Spinnaker

Plugins: GitHub Integration Plugin for Spinnaker Overview

GitHub Integration Plugin features

How the plugin works with GitHub

Compatibility matrix

Installation paths

Plugins: Get Started with the GitHub Integration Plugin

Plugins: Enable and Configure AuthZ in the GitHub Integration Plugin

AuthZ plugin overview

How this feature works

Before you begin

How to enable AuthZ support

Plugins: Enable GitHub Access Validation

Validate GitHub access

How this feature works

How to enable

Plugins: Enable GitHub Commit Status Echo Notifications

Configure GitHub Commit Status Echo notifications

How this feature works

How to enable

Migrating from Echo’s default implementation

Plugins: Use the GitHub Integration Plugin

Before you begin

Trigger GitHub workflows from Spinnaker pipelines

workflow_dispatch event

repository_dispatch event

Trigger Spinnaker pipelines from GitHub workflows

Workflow success trigger

New deployment trigger

Fetch release information

Fetch prerelease information

Create GitHub Commit Status

Plugins: GiHub Integration Plugin Release Notes

v0.3.1 2023/11/21

Features

v0.2.4 2023/11/21

Features

v0.1.2 2023/11/01

Features

v0.1.1 2023/10/18

Fixes

v0.1.0 2023/10/12

Features

Known issues

Armory.Header plugin conflict

Workflow Dispatch and Repository Dispatch run duration

`workflow_dispatch` event

`repository_dispatch` event