Skip to main content
Version: 3.0.0

GitHub

Prerequisites

To complete this how-to guide you need:

  • A GitHub account
  • A terminal with:
    • The Git CLI installed
      • This is typically pre-installed on macOS and Linux, but you can brew install git using Homebrew if needed
    • The GitHub CLI installed
      • brew install gh using Homebrew if needed
    • jq installed
      • brew install jq using Homebrew if needed

Set up variables

Set the GitHub organization and repository to use:

tip

Leave GITHUB_ORGANIZATION empty to use your GitHub username.

GITHUB_ORGANIZATION=""
GITHUB_REPOSITORY="ascend-community"

Choose your Ascend data plane:

DATA_PLANE="bigquery"
tip

Otto's Expeditions is compatible with multiple data planes. You can explore the demo using separate projects for each data plane or create a single project that uses multiple data planes simultaneously. This guide focuses on a single data plane setup.

Check that the GitHub organization is set:

if [ -z "$GITHUB_ORGANIZATION" ]; then
echo "you didn't set a GitHub organization, using your GitHub username..."
GITHUB_ORGANIZATION=$(gh api user | jq -r .login)
fi
echo "$GITHUB_ORGANIZATION/$GITHUB_REPOSITORY"

Copy Ascend Community code to your repository

tip

You can use the following command to check if the repository already exists:

gh repo view $GITHUB_ORGANIZATION/$GITHUB_REPOSITORY

Change the variables above if needed.

Clone the public ascend-io/ascend-community GitHub repository:

gh repo clone ascend-io/ascend-community $GITHUB_REPOSITORY

Change into the repository directory:

cd $GITHUB_REPOSITORY

Remove the .git directory:

rm -rf .git

Initialize a new .git directory:

git init

Create a commit:

git checkout -b main
git add .
git commit -m "copy code from ascend-io/ascend-community"

Create a new private repository:

tip

You can use --internal instead of --private to create an internal repository for GitHub Enterprise.

gh repo create $GITHUB_ORGANIZATION/$GITHUB_REPOSITORY --private --source .

Push the code to the new repository:

git push --set-upstream origin main

Set the root of the project:

PROJECT_ROOT="ottos-expeditions/projects/$DATA_PLANE"

Enable SSH access to the GitHub repository

Ascend requires a private SSH key to access your GitHub repository. You must set the corresponding public SSH key as a deploy key on the GitHub repository.

warning

GitHub does not allow the reuse of SSH deploy keys across repositories.

Set up variables

Choose a name for the SSH key:

SSH_KEY_NAME="ascend_ottos_expeditions"

Create a new SSH key on your local machine

Create a new SSH key:

ssh-keygen -t ed25519 -N "" -f ~/.ssh/$SSH_KEY_NAME

Add the SSH public key as a deploy key to the repository

Add the SSH public key as a deploy key to the repository:

gh repo deploy-key add ~/.ssh/$SSH_KEY_NAME.pub

Confirm in the GitHub UI

Open your repository in the GitHub UI to confirm everything looks correct:

gh repo view --web

Create the Ascend Repository

In the Ascend UI, navigate to Settings > Repositories and click Add Repository.

warning

This section uses | pbcopy to pipe standard output to the clipboard on MacOS for easy copying into the Ascend UI. If you are using a different operating system, adjust the command or manually copy the output after dropping the | pbcopy from each command.

Copy the repository URI

Copy the repository URI to the clipboard:

echo "git@github.com:$GITHUB_ORGANIZATION/$GITHUB_REPOSITORY.git" | pbcopy

Paste it into the Repository URI field in the Ascend UI.

Copy the SSH private key to clipboard

Copy the SSH private key to the clipboard:

cat ~/.ssh/$SSH_KEY_NAME | pbcopy

Paste it into the SSH Private Key field in the Ascend UI.

warning

If you're manually copying the SSH private key, ensure you copy the entire key of the form:

-----BEGIN OPENSSH PRIVATE KEY-----
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
-----END OPENSSH PRIVATE KEY-----

Including the -----BEGIN OPENSSH PRIVATE KEY----- and -----END OPENSSH PRIVATE KEY----- lines.

Click Check and Create.

Create the Ascend Project

In the Ascend UI, navigate to Settings > Projects and click Add Project.

Set the Title to "Otto's Expeditions", or whatever you like! For the Repository field, select the repository you just added from the dropdown.

Copy the Project Root to your clipboard:

echo "$PROJECT_ROOT" | pbcopy

Paste it into the Project Root field in the Ascend UI. Click Save.

Next steps

🎉 Congratulations, you're ready to create an Ascend Workspace and start using Otto's Expeditions!