Armory Docs – Get Started with the GitHub Integration Plugin

Plugins: Install the GitHub Integration Plugin in Armory Continuous Deployment

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

Installation overview

Enabling the GitHub Integration plugin consists of the following steps:

Meet the prerequisites
Create and install a GitHub App
Configure the plugin
Install the plugin

Before you begin

You have read the GitHub Integration Plugin overview.
You are familiar with GitHub Apps.

You are running Armory Continuous Deployment.
You manage your instance using the Armory Operator and the spinnaker-kustomize-patches repo.

Compatibility

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

Create and install a GitHub App

You need to create and install a GitHub App that interacts with the GitHub Integration plugin.

Create a GitHub App. Follow the instructions in GitHub’s Registering a GitHub App guide.
- Provide values for GitHub App name. Homepage URL, and Repository permissions. You do not need to fill out the Identifying and authorizing users, Post installation, or Webhook sections.
- Your GitHub App should have the following Repository permissions:
  - Actions: Read and write
  - Contents: Read and write
  - Deployments: Read and write
  - Environments: Read and write
  - Metadata: Read-only
- You do need to generate a private key (Private keys section).
- Be sure to note the GitHub App’s App ID and Private key. You need these to configure the GitHub Integration plugin.
Install the GitHub App you created either in a specific repo or organization-wide. Follow the instructions in GitHub’s Installing your own GitHub App guide.

Configure the plugin

Create a github-integration-plugin.yml file with the following contents:

apiVersion: spinnaker.armory.io/v1alpha2
kind: SpinnakerService
metadata:
 name: spinnaker
spec:
 spinnakerConfig:
 profiles:
 spinnaker:
 github:
 plugin:
 accounts: []
 spinnaker:
 extensibility:
 repositories:
 repository:
 enabled: true
 url: https://raw.githubusercontent.com/armory-plugins/pluginRepository/master/repositories.json
 deck:
 settings-local.js:
 gate:
 spinnaker:
 extensibility:
 plugins:
 Armory.GitHubIntegration:
 enabled: true
 version: <version>
 deck-proxy:
 enabled: true
 plugins:
 Armory.GitHubIntegration:
 enabled: true
 version: <version>
 orca:
 spinnaker:
 extensibility:
 plugins:
 Armory.GitHubIntegration:
 enabled: true
 version: <version>
 igor:
 spinnaker:
 extensibility:
 plugins:
 Armory.GitHubIntegration:
 enabled: true
 version: <version>
 echo:
 spinnaker:
 extensibility:
 plugins:
 Armory.GitHubIntegration:
 enabled: true
 version: <version>

deck.settings-local.js: Copy the contents of your existing setting-local.js to this section. Add githubWorkflow to the triggerTypes array to enable the GitHub Workflow trigger option. Add githubEvent to the triggerTypes array to enable the GitHub event trigger option for GitHub Deployment events.

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


spec:
 spinnakerConfig:
 profiles:
 spinnaker:
 github:
 plugin:
 accounts: []
 spinnaker:
 extensibility:
 repositories:
 repository:
 enabled: true
 url: https://raw.githubusercontent.com/armory-plugins/pluginRepository/master/repositories.json
 deck:
 settings-local.js: |
 window.spinnakerSettings = {
 ... (content omitted for brevity)
 triggerTypes: [
 'artifactory',
 'concourse',
 'cron',
 'docker',
 'git',
 'githubWorkflow',
 'githubEvent',
 'helm',
 'jenkins',
 'nexus',
 'pipeline',
 'plugin',
 'pubsub',
 'travis',
 'webhook',
 'wercker',
 ]
 ... (content omitted for brevity)
 }

version: Replace <version> with the plugin version compatible with your Spinnaker version.
accounts: Configure the GitHub location(s) where you installed the GitHub App you created. The configuration differs depending on whether you installed the GitHub App organization-wide or with access to individual repositories.

- name: <name>
 organization: <github-organization>
 repository: <github-repository>
 defaultBranch: <default-github-branch>
 githubAppId: <github-app-id>
 githubAppPrivateKey: <github-app-private-key>
 permissions: []

All fields are required.

name: Unique name; this name appears in the GitHub Integration stages’ GitHub Account select list.
organization: GitHub organization that you installed the GitHub App in
repository: The GitHub repository to access
defaultBranch: Default repository branch; for example, main or master
githubAppId: The GitHub App’s App ID
githubAppPrivateKey: The GitHub App’s private key; this field supports encrypted field references; see Work with Secrets in Spinnaker for details.

- name: <name>
 organization: <github-organization>
 orgWideInstallation: true
 includePublicRepositories: false
 defaultBranch: <default-github-branch>
 githubAppId: <github-app-id>
 githubAppPrivateKey: <github-app-private-key>
 permissions: []

All fields are required.

name: Unique name; this name appears in the GitHub Integration stages’ GitHub Account select list.
organization: GitHub organization that you installed the GitHub App in
orgWideInstallation: true
includePublicRepositories: true/false (Optional) Defaults to false. Flag to limit the Spinnaker triggers to only PRIVATE/INTERNAL repositories that the Github App installation has access to.
defaultBranch: Default repository branch; for example, main or master
githubAppId: The GitHub App’s App ID
githubAppPrivateKey: The GitHub App’s private key; this field supports encrypted field references; see Work with Secrets in Spinnaker for details.

Conflict with Armory CDSH v2.30.x

Known issue: The GitHub Integration plugin conflicts with the Armory.Header plugin version included in Armory CD v2.30.x. You must install version 0.2.0 of the Armory.Header plugin.

Show me how

 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

Accounts config example

In this example, you have company-public and company-private GitHub organizations, so you created two GitHub Apps, one for each org.

You installed the GitHub App for the company-private org with access to all repos in the org.
You installed the GitHub App for the company-public org with access to two specific repos in the org.

Your accounts config looks like this:

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: []
 - 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: []

Install the plugin

Add the plugin patch to your Kustomize recipe’s patchesStrategicMerge section. For example:

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


apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

namespace: spinnaker

components:
 - core/base
 - core/persistence/in-cluster
 - targets/kubernetes/default

patchesStrategicMerge:
 - core/patches/oss-version.yml
 - plugins/patch-github-integration-plugin.yml

patches:
 - target:
 kind: SpinnakerService
 path: utilities/switch-to-oss.yml

Apply the updates to your Kustomization recipe.

kubectl apply -k <kustomization-directory-path>

What’s next

Learn how to use the GitHub Integration plugin.

Plugins: Install the GitHub Integration Plugin in Spinnaker (Operator)

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

Installation overview

Enabling the GitHub Integration plugin consists of the following steps:

Meet the prerequisites
Create and install a GitHub App
Configure the plugin
Install the plugin

Before you begin

You have read the GitHub Integration Plugin overview.
You are familiar with GitHub Apps.

You are running open source Spinnaker.
You manage your instance using the Spinnaker Operator and the spinnaker-kustomize-patches repo. If you are using Halyard, see Install the GitHub Integration Plugin in Spinnaker (Halyard).

Compatibility

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

Create and install a GitHub App

You need to create and install a GitHub App that interacts with the GitHub Integration plugin.

Create a GitHub App. Follow the instructions in GitHub’s Registering a GitHub App guide.
- Provide values for GitHub App name. Homepage URL, and Repository permissions. You do not need to fill out the Identifying and authorizing users, Post installation, or Webhook sections.
- Your GitHub App should have the following Repository permissions:
  - Actions: Read and write
  - Contents: Read and write
  - Deployments: Read and write
  - Environments: Read and write
  - Metadata: Read-only
- You do need to generate a private key (Private keys section).
- Be sure to note the GitHub App’s App ID and Private key. You need these to configure the GitHub Integration plugin.
Install the GitHub App you created either in a specific repo or organization-wide. Follow the instructions in GitHub’s Installing your own GitHub App guide.

Configure the plugin

Create a github-integration-plugin.yml file with the following contents:

apiVersion: spinnaker.io/v1alpha2
kind: SpinnakerService
metadata:
 name: spinnaker
spec:
 spinnakerConfig:
 profiles:
 spinnaker:
 github:
 plugin:
 accounts: []
 spinnaker:
 extensibility:
 repositories:
 repository:
 enabled: true
 url: https://raw.githubusercontent.com/armory-plugins/pluginRepository/master/repositories.json
 deck:
 settings-local.js:
 gate:
 spinnaker:
 extensibility:
 plugins:
 Armory.Integration:
 enabled: true
 version: <version>
 deck-proxy:
 enabled: true
 plugins:
 Armory.GithubApi:
 enabled: true
 version: <version>
 orca:
 spinnaker:
 extensibility:
 plugins:
 Armory.Integration:
 enabled: true
 version: <version>
 igor:
 spinnaker:
 extensibility:
 plugins:
 Armory.Integration:
 enabled: true
 version: <version>
 echo:
 spinnaker:
 extensibility:
 plugins:
 Armory.Integration:
 enabled: true
 version: <version>

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


spec:
 spinnakerConfig:
 profiles:
 spinnaker:
 github:
 plugin:
 accounts: []
 spinnaker:
 extensibility:
 repositories:
 repository:
 enabled: true
 url: https://raw.githubusercontent.com/armory-plugins/pluginRepository/master/repositories.json
 deck:
 settings-local.js: |
 window.spinnakerSettings = {
 ... (content omitted for brevity)
 triggerTypes: [
 'artifactory',
 'concourse',
 'cron',
 'docker',
 'git',
 'githubWorkflow',
 'githubEvent',
 'helm',
 'jenkins',
 'nexus',
 'pipeline',
 'plugin',
 'pubsub',
 'travis',
 'webhook',
 'wercker',
 ]
 ... (content omitted for brevity)
 }

version: Replace <version> with the plugin version compatible with your Spinnaker version.
accounts: Configure the GitHub location(s) where you installed the GitHub App you created. The configuration differs depending on whether you installed the GitHub App organization-wide or with access to individual repositories.

- name: <name>
 organization: <github-organization>
 repository: <github-repository>
 defaultBranch: <default-github-branch>
 githubAppId: <github-app-id>
 githubAppPrivateKey: <github-app-private-key>
 permissions: []

All fields are required.

name: Unique name; this name appears in the GitHub Integration stages’ GitHub Account select list.
organization: GitHub organization that you installed the GitHub App in
repository: The GitHub repository to access
defaultBranch: Default repository branch; for example, main or master
githubAppId: The GitHub App’s App ID
githubAppPrivateKey: The GitHub App’s private key; this field supports encrypted field references; see Work with Secrets in Spinnaker for details.

- name: <name>
 organization: <github-organization>
 orgWideInstallation: true
 includePublicRepositories: false
 defaultBranch: <default-github-branch>
 githubAppId: <github-app-id>
 githubAppPrivateKey: <github-app-private-key>
 permissions: []

All fields are required.

name: Unique name; this name appears in the GitHub Integration stages’ GitHub Account select list.
organization: GitHub organization that you installed the GitHub App in
orgWideInstallation: true
includePublicRepositories: true/false (Optional) Defaults to false. Flag to limit the Spinnaker triggers to only PRIVATE/INTERNAL repositories that the Github App installation has access to.
defaultBranch: Default repository branch; for example, main or master
githubAppId: The GitHub App’s App ID
githubAppPrivateKey: The GitHub App’s private key; this field supports encrypted field references; see Work with Secrets in Spinnaker for details.

Save the file to your spinnaker-kustomize-patches/plugins/oss directory.

Accounts config example

In this example, you have company-public and company-private GitHub organizations, so you created two GitHub Apps, one for each org.

You installed the GitHub App for the company-private org with access to all repos in the org.
You installed the GitHub App for the company-public org with access to two specific repos in the org.

Your accounts config looks like this:

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: []
 - 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: []

Install the plugin

Add the plugin patch to your Kustomize recipe’s patchesStrategicMerge section. For example:

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


apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

namespace: spinnaker

components:
 - core/base
 - core/persistence/in-cluster
 - targets/kubernetes/default

patchesStrategicMerge:
 - core/patches/oss-version.yml
 - plugins/oss/github-integration-plugin.yml

patches:
 - target:
 kind: SpinnakerService
 path: utilities/switch-to-oss.yml

Apply the updates to your Kustomization recipe.

kubectl apply -k <kustomization-directory-path>

What’s next

Learn how to use the GitHub Integration plugin.

Plugins: Install the GitHub Integration Plugin in Spinnaker (Halyard)

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

Installation overview

Enabling the GitHub Integration plugin consists of the following steps:

Meet the prerequisites
Create and install a GitHub App
Add the plugin to local config files
Install the plugin

Before you begin

You have read the GitHub Integration Plugin overview.
You are familiar with GitHub Apps.

You are running open source Spinnaker.
You manage your instance using Halyard. If you are using the Spinnaker Operator, see Install the GitHub Integration Plugin in Spinnaker (Operator).

A note about installing plugins in Spinnaker

When Halyard adds a plugin to a Spinnaker installation, it adds the plugin repository information to all services, not just the ones the plugin is for. This means that when you restart Spinnaker, each service restarts, downloads the plugin, and checks if an extension exists for that service. Each service restarting is not ideal for large Spinnaker installations due to service restart times. Clouddriver can take an hour or more to restart if you have many accounts configured.

The GitHub Integration plugin extends Deck, Echo, Gate, Igor, and Orca. To avoid every Spinnaker service restarting and downloading the plugin, do not add the plugin using Halyard. Instead, follow the local config installation method, in which you configure the plugin in each extended service’s local profile.

Compatibility

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

Create and install a GitHub App

You need to create and install a GitHub App that interacts with the GitHub Integration plugin.

Create a GitHub App. Follow the instructions in GitHub’s Registering a GitHub App guide.
- Provide values for GitHub App name. Homepage URL, and Repository permissions. You do not need to fill out the Identifying and authorizing users, Post installation, or Webhook sections.
- Your GitHub App should have the following Repository permissions:
  - Actions: Read and write
  - Contents: Read and write
  - Deployments: Read and write
  - Environments: Read and write
  - Metadata: Read-only
- You do need to generate a private key (Private keys section).
- Be sure to note the GitHub App’s App ID and Private key. You need these to configure the GitHub Integration plugin.
Install the GitHub App you created either in a specific repo or organization-wide. Follow the instructions in GitHub’s Installing your own GitHub App guide.

Add the plugin to local config files

settings-local.js

Add github to the triggerTypes array in your existing settings-local.js file:

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


window.spinnakerSettings = {
...
triggerTypes: [
 'artifactory',
 'concourse',
 'cron',
 'docker',
 'git',
 'githubWorkflow',
 'githubEvent',
 'helm',
 'jenkins',
 'nexus',
 'pipeline',
 'plugin',
 'pubsub',
 'travis',
 'webhook',
 'wercker',
 ]
...
}

Service config files

Update echo-local.yml, gate-local.yml, igor-local.yml, and orca-local.yml config files with the following:

spinnaker:
 extensibility:
 plugins:
 Armory.Integration:
 id: Armory.Integration
 enabled: true
 version: <version>
 repositories:
 githubIntegration:
 enabled: true
 url: https://raw.githubusercontent.com/armory-plugins/pluginRepository/master/repositories.json
github:
 plugin:
 accounts: []

version: Replace <version> with the plugin version compatible with your Spinnaker version.
accounts: Configure the GitHub location(s) where you installed the GitHub App you created. The configuration differs depending on whether you installed the GitHub App organization-wide or with access to individual repositories.

- name: <name>
 organization: <github-organization>
 repository: <github-repository>
 defaultBranch: <default-github-branch>
 githubAppId: <github-app-id>
 githubAppPrivateKey: <github-app-private-key>
 permissions: []

All fields are required.

name: Unique name; this name appears in the GitHub Integration stages’ GitHub Account select list.
organization: GitHub organization that you installed the GitHub App in
repository: The GitHub repository to access
defaultBranch: Default repository branch; for example, main or master
githubAppId: The GitHub App’s App ID
githubAppPrivateKey: The GitHub App’s private key; this field supports encrypted field references; see Work with Secrets in Spinnaker for details.

- name: <name>
 organization: <github-organization>
 orgWideInstallation: true
 includePublicRepositories: false
 defaultBranch: <default-github-branch>
 githubAppId: <github-app-id>
 githubAppPrivateKey: <github-app-private-key>
 permissions: []

All fields are required.

name: Unique name; this name appears in the GitHub Integration stages’ GitHub Account select list.
organization: GitHub organization that you installed the GitHub App in
orgWideInstallation: true
includePublicRepositories: true/false (Optional) Defaults to false. Flag to limit the Spinnaker triggers to only PRIVATE/INTERNAL repositories that the Github App installation has access to.
defaultBranch: Default repository branch; for example, main or master
githubAppId: The GitHub App’s App ID
githubAppPrivateKey: The GitHub App’s private key; this field supports encrypted field references; see Work with Secrets in Spinnaker for details.

Accounts config example

In this example, you have company-public and company-private GitHub organizations, so you created two GitHub Apps, one for each org.

You installed the GitHub App for the company-private org with access to all repos in the org.
You installed the GitHub App for the company-public org with access to two specific repos in the org.

Your accounts config looks like this:

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: []
 - 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: []

Deck plugin

Configure the Deck plugin in your gate-local.yml config file:

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


spinnaker:
 extensibility:
 plugins:
 Armory.Integration:
 id: Armory.Integration
 enabled: true
 version: <version>
 repositories:
 githubIntegration:
 enabled: true
 url: https://raw.githubusercontent.com/armory-plugins/pluginRepository/master/repositories.json
 deck-proxy:
 enabled: true
 plugins:
 Armory.Integration:
 enabled: true
 version: <version>
github:
 plugin:
 accounts: [] 

Install the plugin

Apply your changes:

hal deploy apply

What’s next

Learn how to use the GitHub Integration plugin.