Install the GitHub Integration Plugin in Spinnaker (Halyard)

Installation overview

Enabling the GitHub Integration plugin consists of the following steps:

1. Meet the prerequisites
2. Create and install a GitHub App
3. Add the plugin to local config files
4. 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).

Compatibility

Create and install a GitHub App

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

1. 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.

2. 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.

• Account Config:
• Individual Repo
• All Repos in Org

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

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

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.