Github

Overview

The Tempest GitHub integration enables Tempest to manage your repositories and commonly used resources as part of project orchestration. Tempest also uses events from configured repositories to facilitate orchestration for preview environments. For example, preview environments can be provisioned when a pull request is opened and cleaned up when a pull request is closed.

Every Tempest recipe and project starts with a GitHub repository, which can either be imported or created as new.

Authentication

Tempest supports three methods of authentication to connect Tempest with Github.

• Tempest Github App (preferred)
• OAuth 2.0
• Personal Access Tokens

Tempest GitHub App

The Tempest GitHub App is the preferred method of authentication to link Tempest with GitHub. By authenticating via the App experience, users can connect their resource accounts without sharing credentials, allowing for streamlined permissions management and automated workflows within their familiar platforms.

To connect:

1. Go to Recipes and select “Create Recipe.”
2. A GitHub resource will automatically be added to your Recipe. Select the resource.
3. Select “Add credentials” and then “+Link credentials.”
4. Select “Github App” and “Authenticate with Github.”
5. Review the accesses and select “Authorize.”
6. Select which GitHub organization you want to connect with Tempest.
7. Follow through for authentication.

OAuth 2.0

OAuth2 will provide a scoped access token attached to your user. This token will request the repo scope by default.

To connect:

1. Go to Recipes and select “Create Recipe.”
2. A GitHub resource will automatically be added to your Recipe. Select the resource.
3. Select “Add credentials” and then “+Link credentials.”
4. Select “OAuth.”
5. Review the accesses and select “Authorize.”
6. Follow through for authentication.

Personal Access Token

Tempest supports both fine-grained and classic Personal Access Tokens, though GitHub recommends using fine-grained tokens where possible.

Note: Personal Access Tokens do not provide Webhook integration, preventing full use of GitHub within Tempest.

Fine-grained personal access token

1. Refer to GitHub’s documentation on how to generate a fine-grained personal access token.
2. In Repository access, select “All repositories.” This allows Tempest to read existing repositories and orchestrate provisioning new ones.
3. Under Repository permissions, select the following:
   • Administration: Read & write
   • Commit statuses: Read
   • Contents: Read & write
   • Deployments: Read & write
   • Environments: Read & write
   • Pull requests: Read
   • Webhooks: Read & write
   • Workflows: Read & write
4. Save your access token somewhere safe and use it when connecting to Github via Tempest Link.

Classic personal access token

1. Refer to GitHub’s documentation on how to generate a classic personal access token.
2. Under Select scopes, check:
   • repo (and all sub-options)
   • workflow
   • delete_repo
3. Save your access token somewhere safe and use it when connecting to Github via Tempest Link.

Resources

Repository

The Repository resource represents a GitHub repository. This is a parent resource for the Repository File, Workflow, Deploy Key, and Deployment sub resources.

Create Input

• Name (required): The name of the repository. It must contain only alphanumeric characters, underscores, hyphens, and periods.
• Visibility: Choose between "public" or "private". The default is set to "private".
• Enable Dependabot: A boolean option to enable or disable Dependabot for the repository. It's enabled by default.
• Template repository: A boolean option to specify if the repository should be a template. It's set to false by default.
• Create from template: An option to create the repository from an existing template. This field uses a data source to populate available templates based on the organization.

Properties

Name	Description
Name	The name of the Repository
HTML URL	Link to browsable view of the Repository
HTTPS Clone URL	Link to clone the Repository using HTTPS
SSH Clone URL	Link to clone the Repository using SSH
Description	Brief description of the Repository
Full Name	The full name of the Repository (e.g., "org/repo")
Visibility	The visibility of the Repository
Provider	The provider of the Repository (always "github")
Default Branch	The default branch of the Repository

Repository File

The Repository File resource represents a file within a GitHub repository. This is a sub resource of the Repository parent resources.

Create Input

• File (required): The full path to the file in the repository. For example, "src/main.js" or "Dockerfile".
• File Content (required): The content of the file. This is a multi-line text field where you can enter the file's contents, or upload a file.
• Create Pull Request: An optional boolean field. If checked, it will create a pull request to the default branch after the file is created. By default, this is set to false.

Properties

Name	Description
Name	The name of the file
Path	The full path to the file in the repository
HTML URL	The URL to view the file in a browser
Git SHA	The SHA hash of the file

Workflow

The Workflow resource represents a GitHub Workflow within a GitHub repository. This is a sub resource of the Repository parent resources.

Create Input

• Mode (required): Select the configuration mode for the workflow. Options are "Tempest Built-in" or "Custom". Default is "Tempest Built-in".
  • Workflow Template: If "Tempest Built-in" mode is selected, choose the built-in workflow template. Currently, only "Docker Build" is available.
  • Workflow Filename: If "Custom" mode is selected, specify the name of the workflow file (e.g., "build.yaml", "ci.yaml").
  • Workflow Content: If "Custom" mode is selected, provide the content of the workflow file. This is a multi-line text field.
• Create Pull Request: An optional boolean field. If checked, it will create a pull request to the default branch after the workflow is created. Default is false.

Properties

Name	Description
ID	The unique identifier of the Workflow in GitHub
Name	The name of the Workflow
Path	The full path to the Workflow file in the repository
State	The current state of the Workflow (e.g., active, deleted)
HTML URL	The URL to view the Workflow in the GitHub web interface

Deploy Key

A Deploy Key resource represents a configured Deploy Key within a GitHub Repository. This is a sub resource of the Repository parent resources.

Create Input

• Title: The title of the deploy key. Default is "Tempest Deploy Key".
• Public Key (required): The public key of the SSH key pair. This is a multi-line text field where you can enter or upload the public key.

Properties

Name	Description
ID	Unique identifier of the Deploy Key in GitHub
Public Key	The public key configured for the Deploy Key
HTML URL	URL to the Deploy Key in the GitHub web interface

Deployment

A Deployment resource represents a Deployment on a GitHub Repository. This is a sub resource of the Repository parent resources.

Create Input

• Reference Branch: The branch to create the deployment for. If not specified, it defaults to the target repository's default branch. For example, ‘main’.
• Environment: The name of the environment for the deployment, such as 'production' or 'staging'. Default is set to 'production'.
• Description: A description of the change being made. If not provided, it defaults to "Deployed by Tempest."

Properties

Name	Description
Description	Short description of the deployment
Environment	Name for the target deployment envirnment
ID	Unique identifier of the deployment in GitHub
Git Ref	The git ref (branch) thatwas deployed
Git SHA	Git SHA that was deployed
HTML URL	The URL to view the deployment in a browser