Install the GitHub Integration Plugin in Armory Continuous Deployment

Installation overview

Enabling the GitHub Integration plugin consists of the following steps:

1. Meet the prerequisites
2. Create and install a GitHub App
3. Configure the plugin
4. 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

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.

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.

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

 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

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

2. Apply the updates to your Kustomization recipe.

   kubectl apply -k <kustomization-directory-path>
   

What’s next

Learn how to use the GitHub Integration plugin.