Lightning.VersionControl (Lightning v2.19.0-pre)

View Source

Boundary module for handling Version control activities for project, jobs workflows etc Use this module to create, modify and delete connections as well as running any associated sync jobs

Summary

Functions

create_github_connection(attrs, user)

Creates a connection between a project and a github repo

delete_github_oauth_grant(user)

Deletes the authorization for the github app and updates the user details accordingly

exchange_code_for_oauth_token(code)

Fetches the oauth access token using the code received from the callback url For more info: https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app

fetch_installation_repos(installation_id)
fetch_repo_branches(user, installation_id, repo_name)

Fetches a repository's branches for user.

fetch_user_access_token(user)

Fecthes the access token for the given User. If the access token has expired, it refreshes the token and updates the User column accordingly

fetch_user_installations(user)
get_repo_connection_for_project(project_id)
get_repo_connection_for_token(token)
github_enabled?()
initiate_sync(repo_connection, commit_message)

Fires the GitHub Action that pulls the project spec and commits it.

oauth_token_valid?(token)

Checks if the given token has expired. GitHub supports access tokens that expire and those that don't. If the access token expires, then a refresh token is also availed. This function simply checks if the token has a refresh_token, if yes, it proceeds to check the expiry date

reconfigure_github_connection(repo_connection, params, user)
refresh_oauth_token(refresh_token)

Fetches a new access token using the given refresh token For more info: https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/refreshing-user-access-tokens

remove_github_connection(repo_connection, user)

Deletes a github connection

save_oauth_token(user, token, opts \\ [notify: true])
subscribe(user)

See Lightning.VersionControl.Events.subscribe/1.

verify_github_connection(repo_connection)

Functions

create_github_connection(attrs, user)

@spec create_github_connection(map(), Lightning.Accounts.User.t()) ::
  {:ok, Lightning.VersionControl.ProjectRepoConnection.t()}
  | {:error,
     Ecto.Changeset.t()
     | Lightning.Extensions.UsageLimiting.message()
     | binary()}

Creates a connection between a project and a github repo

delete_github_oauth_grant(user)

@spec delete_github_oauth_grant(Lightning.Accounts.User.t()) ::
  {:ok, Lightning.Accounts.User.t()} | {:error, map()}

Deletes the authorization for the github app and updates the user details accordingly

exchange_code_for_oauth_token(code)

@spec exchange_code_for_oauth_token(code :: String.t()) ::
  {:ok, map()} | {:error, map()}

Fetches the oauth access token using the code received from the callback url For more info: https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app

fetch_installation_repos(installation_id)

fetch_repo_branches(user, installation_id, repo_name)

Fetches a repository's branches for user.

The GitHub App private key can mint an installation token for any installation of the shared App, so this verifies (using the user's own GitHub OAuth grant, via /user/installations) that installation_id is one the user can access before using the app credential. Without this check a user could read branch names from a private repository in another tenant's installation (a confused-deputy). GitHub's installation token then scopes repository access to that installation.

fetch_user_access_token(user)

@spec fetch_user_access_token(Lightning.Accounts.User.t()) ::
  {:ok, String.t()} | {:error, map()}

Fecthes the access token for the given User. If the access token has expired, it refreshes the token and updates the User column accordingly

fetch_user_installations(user)

get_repo_connection_for_project(project_id)

get_repo_connection_for_token(token)

github_enabled?()

initiate_sync(repo_connection, commit_message)

@spec initiate_sync(
  repo_connection :: Lightning.VersionControl.ProjectRepoConnection.t(),
  commit_message :: String.t()
) ::
  :ok
  | {:error, Lightning.Extensions.UsageLimiting.message() | map() | binary()}

Fires the GitHub Action that pulls the project spec and commits it.

The export runs here first and its result is thrown away. The Action fetches /api/provision/:id.yaml, and a 400 there lands in a GitHub Actions log Lightning cannot read, so the user sees a sync that failed with no reason. Costs one extra full spec generation on every successful sync.

oauth_token_valid?(token)

@spec oauth_token_valid?(token :: map()) :: boolean()

Checks if the given token has expired. GitHub supports access tokens that expire and those that don't. If the access token expires, then a refresh token is also availed. This function simply checks if the token has a refresh_token, if yes, it proceeds to check the expiry date

reconfigure_github_connection(repo_connection, params, user)

@spec reconfigure_github_connection(
  Lightning.VersionControl.ProjectRepoConnection.t(),
  map(),
  Lightning.Accounts.User.t()
) ::
  :ok
  | {:error, Lightning.Extensions.UsageLimiting.message() | map() | binary()}

refresh_oauth_token(refresh_token)

@spec refresh_oauth_token(refresh_token :: String.t()) ::
  {:ok, map()} | {:error, map()}

Fetches a new access token using the given refresh token For more info: https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/refreshing-user-access-tokens

remove_github_connection(repo_connection, user)

Deletes a github connection

save_oauth_token(user, token, opts \\ [notify: true])

@spec save_oauth_token(Lightning.Accounts.User.t(), map(), [{:notify, boolean()}]) ::
  {:ok, Lightning.Accounts.User.t()} | {:error, Ecto.Changeset.t()}

subscribe(user)

See Lightning.VersionControl.Events.subscribe/1.

verify_github_connection(repo_connection)

@spec verify_github_connection(
  repo_connection :: Lightning.VersionControl.ProjectRepoConnection.t()
) ::
  :ok | {:error, Lightning.VersionControl.GithubError.t() | map()}