Configure Spinnaker to use Github as an Artifact Source

Configuring a Github Trigger

Spinnaker 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 documentation has concise instructions for configuring Github webhooks.

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

This is just a quick walkthrough of how to configure your Spinnaker to access a Github repo as a source of artifacts. Many of the commands below have additional options that may be useful (or possibly required). If you need more detailed help, take a look at the Halyard command reference if you’re deploying Spinnaker with Halyard.

Enable Github Artifacts

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

Operator

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

Halyard

hal config features edit --artifacts true
hal config artifact github enable

Add a Github Credential

To access private Github repositories, you’ll need a Github “Personal Access Token”. This can be generated by going to the “Settings” page in Github, then clicking on “Developer Settings” and then “Personal Access Token”. The token will need 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. This can be done with a command like this:

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

Operator

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:passwordto use for GitHub authentication. This fields supports `encryptedFilereferences to secrets.
            # tokenFile: token.txt # File containing a GitHub authentication tokenThis 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.

Don’t forget to apply your changes:

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

Halyard

GITHUB_ACCOUNT_NAME=github_user
hal config artifact github account add ${GITHUB_ACCOUNT_NAME} \
    --token # you'll be prompted for this interactively

Detailed information on all command line options can be found here.

Don’t forget to run hal deploy apply to apply your changes.

Using the Github Credential

You may note that the above Github “account” doesn’t actually have a 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. There are a couple ways to use this credential, one example of which is detailed here:

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 (www.github.com), 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 an 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.