server icon indicating copy to clipboard operation
server copied to clipboard

feat: opt-in gh app integration

Open plyr4 opened this issue 4 months ago • 0 comments

this PR adds opt-in GitHub App integrations to the server.

the main differences are:

  • integrate with an OAuth GitHub App by providing an app id and private key
  • use the GitHub App to generate the .netrc password for builds when the app is installed and it can access the repo
  • adds webhook handlers for GitHub App installation and installation_repositories events, and syncs existing repos when changes are made
  • adds Checks functionality, pulled from the original hackathon efforts #1070

New Flags

Key Description Default Value
VELA_SCM_APP_ID set to the App ID for the GitHub App N/A
VELA_SCM_APP_PRIVATE_KEY the string value for the GitHub App private key generated through GitHub N/A

Required GitHub App Configurations

Permissions

the GitHub App requires the following permissions at the very minimum:

  • contents:write
  • checks:write

builds would request write permissions through the git yaml block, see below.

Subscribed Events

  • Installation target

OAuth

the same configurations and oauth scopes should be assigned to the GitHub App, including:

  • oauth callback url set to /authenticate (like usual)
  • Webhook URL set to the base url (like usual)

New YAML block: git

integrating with a GitHub App allows the use of the git YAML block for customizing the permissions allocated to the netrc password embedded into Vela steps.

git:
  token:
    repositories:
      - foo/bar
      - helloworld
    permissions:
      contents: write
      checks: write

this lets users customize the list of repositories that the netrc password has access to, but that list is restricted to ONLY the repos that the GitHub App org installation has been given access to.

by default, the compiler will use the following configurations unless otherwise provided:

git:
  token:
    repositories:
      - VELA_BUILD_REPO
    permissions:
      contents: read
      checks: write

:warning: Considerations

this WILL impact builds, check out the following list of things to consider when migrating to GitHub App

Cloning Private Resources

due to the new restrictive policies set on the netrc token, Vela builds might lose the ability to read/write from certain private repos that the repo owner may have had access to.

GitHub Apps do not support providing access to repos that are outside the installation org. meaning, for a Vela build to access private repos, Go modules, etc, then the build author must provide override the clone step and use an alternative authentication method like a PAT

plyr4 avatar Oct 25 '24 16:10 plyr4