Allow configuration of pipeline permissions

[jamestelfer]

Tokens issued by the service become more useful when they can be used for GitHub API requests outside Git operations.

Incorporate a simple YAML configuration file that

• Defines the default permissions to give to a pipeline (default none)
• Allows for an allow list of pipelines to vend tokens for
• A pipeline may have specific permissions granted to it
• a pipeline definition MAY specify the repository it must be linked to

Bear in mind that periodic retrieval and online reloads will be expected to occur in the future.

The file should be retrieved from the default branch of a configured Git repository.

Out of scope for now:

• multiple repositories per pipeline (for now)
• Periodic retrieval

[dstrates]

@jamestelfer some initial thoughts on this:

• the config file may be in a centralised repo?
• the config file may be in each repo associated with a pipeline?
• both of the above options (i.e. global config and local config)
  • if both: should local config override global config?

[jamestelfer]

To lay out my thinking more completely:

1. The configuration file can be YAML, stored in a single centralized repository location
2. Configuration will only be read from the default branch of that repo
3. The repository name and path will be configurable.
4. Configuration is by an environment variable, read using the internal/config package. The name would be something like REPOSITORY_CONFIGURATION_URN="github:org/repo/path.yaml", using a URL format that is easily parsed by the url package.
5. File format will have something like (spitballing here)

default:
  permissions: # empty list, no permissions granted
    - "content:read"
  repositories:
    - name: "org/privaterepo" # optional list of repositories to give access by default
       permissions: ["content:read"] # optional, defaults to permissions above
    - name: "org/otherrepo"

pipelines:
  - name: "pipeline name"
    repositories:
      # potentially implicit here is content:read for the repo of the pipeline
      - name: "org/repo1" # overlap here with defaults results in a union of the available properties
        permissions: ["content:read", "pull-request:write"]
      - name: "org/repo2"
        permissions: ["content:read", "pull-request:write"]

I'm not devoted to this format. Octo STS has a format that is based on the JWT claims instead of the explicit Buildkite theming here. This also allows different permissions for different repositories, something that GitHub doesn't do: its model is the intersection of a set of repos and permissions. In order to support the above model, the token endpoint would need to be able to specify a repository name that permissions are required for (this could be optional).

If the permissions can vary by the [pipeline,repo] tuple, token caching needs to be changed to use this pair as the cache key.

6. The GitHub token client in internal/github should take a service that supplies the permissions for a given pipeline. This is then supplied to GitHub and the generated token returned.

Thoughts?

[dstrates]

This is very well thought out, thanks for the details.

My only suggestion is that while there's no harm including a REPOSITORY_CONFIGURATION_URN environment variable, it may be more intuitive to automatically source configuration from a <config-name>.yaml file located anywhere in the repository?

[jamestelfer]

When you say "the repository" do you mean the repository that the token is being requested for?

That is, a configuration YAML that exists in a single repository of a given organization, or, one config for each repository that may be accessed, stored in that target repository itself?