Manual Repository

Ascend Projects require a Git repository to store your code. Choose one of the following options to set up your repository and connect it to your Ascend Instance.

Set up a Git repository

Ascend-managed Repository

Refer to this guide to use an Ascend-managed Repository.

Sample Project repository

1. Create a new repository on GitHub

• Navigate to GitHub's New Repository page
• Set Owner to your personal GitHub account or organization
  tip

  If you have permissions to your company's GitHub Organization, create the repository there. Otherwise, create it under your personal account.

• Set Repository name to ascend-quickstart-bigquery (or your preferred name)
• Set Description to Ascend Quickstart BigQuery
• Set visibility to Private
• Click Create repository

2. Clone the Ascend Community Repository and push it to your new repository

# Set the variables
GITHUB_ORG="<your-github-org>" # Use your GitHub username or organization name
GITHUB_REPO="ascend-quickstart-bigquery"

# Clone the Ascend Community Repository
git clone git@github.com:ascend-io/ascend-community.git ${GITHUB_REPO}
cd ${GITHUB_REPO}

# Set the remote URL to your new repository
git remote set-url origin git@github.com:${GITHUB_ORG}/${GITHUB_REPO}.git

# Push the code to your new repository
git push -u origin main

info

If you encounter this error: git@github.com: Permission denied (publickey), follow the SSH steps outlined below before creating your repository.

For more detailed setup instructions for using Otto's Expeditions on your preferred GitHub provider, refer to our how-to guides for GitHub, GitLab, and Bitbucket.

Existing repository

Ensure your repository follows the Ascend Project structure. Your repository should include:

Required:

• ascend_project.yaml and pyproject.toml configuration files (empty placeholders are acceptable initially)
• profiles folder with template Profiles for Parameter management
• connections folder for data source configurations
• flows folder containing your data Flows, each with components and tests subfolders

Optional (add as needed):

• src and templates folders for Applications
• automations folder for Automations
• data folder for local files

tip

Store all secrets securely in your Ascend Vault, not in your repository.

Your repository file structure should look like this:

├── ascend_project.yaml
├── pyproject.toml
├── automations
│   ├── example_automation.yaml
├── connections
│   ├── example_connection.yaml
├── data
│   ├── example_local_data.csv
├── flows
│   ├── example_flow
│       ├── components
│       │   ├── example_python_component.py
│       │   ├── example_sql_component.sql
│       ├── tests
│       │   ├── example_test.py

Connect Ascend to your Git repository

Create the SSH key pair

Linux

1. On your local machine, open a terminal and run the following command:

   mkdir -p ~/.ssh && ssh-keygen -t ed25519 -f ~/.ssh/ascend_quickstart_repo_key -q -N ""

2. This command will generate a new SSH key pair in the ~/.ssh directory.

3. The public key will be saved in ~/.ssh/ascend_quickstart_repo_key.pub

4. The private key will be saved in ~/.ssh/ascend_quickstart_repo_key.

   tip

   You can copy the contents of a file (eg: the public key) to your clipboard by running:

   cat ~/.ssh/ascend_quickstart_repo_key.pub | xclip -selection clipboard

   Or if xclip is not installed:

   cat ~/.ssh/ascend_quickstart_repo_key.pub

   and manually copy the output.

Mac

1. On your local machine, open a terminal and run the following command:

   mkdir -p ~/.ssh && ssh-keygen -t ed25519 -f ~/.ssh/ascend_quickstart_repo_key -q -N ""
2. This command will generate a new SSH key pair in the ~/.ssh directory.
3. The public key will be saved in ~/.ssh/ascend_quickstart_repo_key.pub
4. The private key will be saved in ~/.ssh/ascend_quickstart_repo_key.
   tip

   You can copy the contents of the public key to your clipboard by running:

   cat ~/.ssh/ascend_quickstart_repo_key.pub | pbcopy

Windows

1. On your local machine, open PowerShell and run the following commands:

   # Create .ssh directory if it doesn't exist
   New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.ssh"
   
   # Generate SSH key
   ssh-keygen -t ed25519 -f "$env:USERPROFILE\.ssh\ascend_quickstart_repo_key" -N '""'
2. This command will generate a new SSH key pair in the .ssh directory within your user profile folder.
3. The public key will be saved in %USERPROFILE%\.ssh\ascend_quickstart_repo_key.pub
4. The private key will be saved in %USERPROFILE%\.ssh\ascend_quickstart_repo_key.
   tip

   You can copy the contents of the public key to your clipboard by running:

   Get-Content "$env:USERPROFILE\.ssh\ascend_quickstart_repo_key.pub" | Set-Clipboard

Add the public key to your repository

Bitbucket

To allow for Ascend to have write access to your Bitbucket repository, you will need to add your public key to a Bitbucket account with write access, not to the repository itself.

Please follow the instructions under Provide Bitbucket Cloud with your public key to add the public ssh key to a Bit Bucket user.

GitHub

Please follow the instructions here to setup the public ssh key in your Github repository. You will need to allow write access.

GitLab

Please follow the instructions here to setup the public ssh key in your Gitlab repository. You will to need to grant write permissions to the key.

Add the private key to Ascend

1. In the Ascend UI, navigate to the instance settings by clicking on the button in the top right with your instance name and your user icon.
2. Click on the Repositories settings tab.
3. Click the Add Repository button.
4. Set the Repository URI in this format: git@github.com:<github-org>/<github-repo>.git.
5. Set SSH Private Key to the private key you generated in the previous step.

tip

Make sure to copy the entire private key, including the lines that indicate the beginning and end of the key.

1. Click Check and Create.

Next steps

Connect your newly created Ascend-managed Repository to a Project and begin building in the Ascend platform.