Connect GitHub as an Artifact Source in Spinnaker

Configure a GitHub trigger in Spinnaker

Spinnaker^TM pipelines can be configured to trigger when a change is committed to a GitHub repository. This doesn’t require any configuration of Spinnaker other than adding a GitHub trigger but does require administration of the GitHub repositories to configure the webhook.

The open source Spinnaker documentation has concise instructions for configuring GitHub webhooks.

Configure GitHub as an artifact source

If you actually want to use a file from the GitHub commit in your pipeline, you’ll need to configure GitHub as an artifact source in Spinnaker.

Many of the commands below have additional options that may be useful (or possibly required).

Enable GitHub artifacts

If you haven’t done this yet (for example, if you’ve just installed Armory Spinnaker fresh), you need to enable GitHub as an artifact source:

Add the following snippet to SpinnakerService manifest:

apiVersion: spinnaker.armory.io/v1alpha2
kind: SpinnakerService
metadata:
  name: spinnaker
spec:
  spinnakerConfig:  
    config:
      features:
        artifacts: true
      artifacts:
        github:
          enabled: true

Add a GitHub credential

To access private GitHub repositories, you need a GitHu bPersonal Access Token. See the GitHub docs for instructions. The token needs the repo scope.

Once you have a token, you should provide that token for Spinnaker’s Igor service as a credential to use to access GitHub.

Replace the account name github_user with the string you want to use to identify this GitHub credential.

Add the following snippet to SpinnakerService manifest:

apiVersion: spinnaker.armory.io/v1alpha2
kind: SpinnakerService
metadata:
  name: spinnaker
spec:
  spinnakerConfig:  
    config:
      features:
        artifacts: true
      artifacts:
        github:
          enabled: true
          accounts:
          - name: github_user
            token: abc  # GitHub's personal access token. This fields supports `encrypted` references to secrets.
            # username: abc # GitHub username
            # password: abc # GitHub password. This fields supports `encryptedreferences` to secrets.
            # usernamePasswordFile: creds.txt # File containing "username:password" to use for GitHub authentication. This fields supports `encryptedFilereferences` to secrets.
            # tokenFile: token.txt # File containing a GitHub authentication token. This fields supports `encryptedFile` references to secrets.

If you have a GitHub Personal Access Token, you only need that to authenticate against GitHub, but there are other authentication options like username/password, or specifying credentials in a file entry.

Apply your changes:

kubectl -n >spinnaker namespace> apply -f <SpinnakerService manifest>

Using the GitHub credential

You may note that the above GitHub “account” doesn’t actually have an endpoint for your GitHub. This account is basically just the credential used by Spinnaker artifacts to access GitHub. The actual GitHub API endpoint is specified in the artifact reference. The following is an example of how to use this credential.

Pulling a Kubernetes Manifest from Github

1. Under Expected Artifacts in your pipeline, create an artifact of type GitHub.

2. Specify the file path as the path within the repository to your file. For example, if your manifest is at demo/manifests/deployment.yml in the Github repository orgname/reponame , specify demo/manifests/deployment.yml.

3. Check the Use Default Artifact checkbox.

4. In the Content URL, provide the full path to the API URI for your manifest. Here are some examples of this:

   • If you’re using SaaS GitHub, the URI is generally formatted like this: https://api.github.com/repos/<ORG>/<REPO>/contents/<PATH-TO-FILE>.

     • For example: https://api.github.com/repos/armory/demo/contents/manifests/deployment.yml

   • If you have on-prem Github Enterprise, then the URI may be formatted like this: https://<GITHUB_URL>/api/v3/repos/<ORG>/<REPO>/contents/<PATH-TO-FILE>.

     • For example: http://github.customername.com/api/v3/repos/armory/spinnaker-pipelines/contents/manifests/deployment.yml

5. Create a Deploy (Manifest) stage. Rather than specifying the manifest directly in the UI, under the Manifest Source specify Artifact, and in the Expected Artifact field, select the artifact you created above.

6. If you have multiple Github Accounts (credentials) added to your Spinnaker cluster, there should be a dropdown to select which one to use.

Troubleshooting credentials and URIs

To verify that your token and URI are correct, you can run a curl command to test authentication (the user field doesn’t matter):

curl https://api.github.com/repos/armory/demo/contents/manifests/deployment.yml \
  -u nobody:abcdef0123456789abcdef0123456789abcdef01

If you receive metadata about your file, the credential and URI are correct.