> ## Documentation Index
> Fetch the complete documentation index at: https://grandcentral.backbase.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Repository provisioning workflow

> Initial repository setup and configuration for AI agents

The repository provisioning workflow automatically sets up new agent repositories when they are cloned or created from a template.

When a new repository is created from a template, the workflow:

1. Detects initial commit
2. Sets up project configuration
3. Baselines service version
4. Provisions Python project structure

## Workflow triggers

The provisioning workflow is triggered on:

* **Initial Push**: First push to develop branch
* **Manual Trigger**: Via workflow\_dispatch

The workflow only runs if:

* It's the first workflow run (`github.run_number == 1`)
* The pusher name starts with `gc-tfrw-` (Terraform workflow bot)

## Provisioning process

### 1. project setup

The workflow sets up the project:

* **Authentication**: Uses GitHub App for authentication
* **Repository Access**: Checks out code with proper permissions
* **Token Generation**: Creates GitHub token for subsequent steps

### 2. Python project provisioning

The workflow provisions the Python project:

* **Package Configuration**: Sets up package name based on repository name
* **Project Structure**: Creates standard Python project structure
* **Version Baseline**: Sets initial version in project files

## Workflow flowchart

```mermaid theme={"system"}
%%{init: {
  'theme': 'base',
  'themeVariables': {
    'primaryColor': '#ffffff',
    'primaryBorderColor': '#295eff',
    'primaryTextColor': '#091c35',
    'lineColor': '#091c35',
    'secondaryColor': '#f3f6f9',
    'tertiaryColor': '#ebf0f5',
    'fontFamily': 'Libre Franklin, sans-serif'
  }
}}%%
flowchart TD
    Start([Push to develop<br/>or manual trigger]) --> CheckConditions{First run?<br/>Pusher = gc-tfrw-*}
    CheckConditions -->|No| End([End])
    CheckConditions -->|Yes| Setup[Setup project<br/>Authenticate with GitHub App]
    Setup --> Provision[Provision Python project<br/>Update pyproject.toml<br/>Create CHANGELOG.md<br/>Create/update README.md<br/>Regenerate uv.lock]
    Provision --> Commit[Commit and push<br/>to develop and main]
    Commit --> End([Repository provisioned])
```

## Workflow configuration

The repository provisioning workflow is defined in `.github/workflows/repository-provisioning.yaml`:

```yaml theme={"system"}
name: Provision repository on initial commit
### # this workflow is intended to run on repo cloning/templating
# Baseline the version in pyproject.toml
### On:
    push:
        branches:
            - develop
    workflow_dispatch:
jobs:
    provision:
        runs-on: ubuntu-latest
        if: | # Check GitHub workflow run number and repository pusher name
            github.run_number == 1 && startsWith(github.event.pusher.name, 'gc-tfrw-')
        name: Provision project
        timeout-minutes: 10
        steps:
            - name: Setup project
              uses: backbase-common/gc-ai-workflows/setup-project@main
              with:
                  ref: ${{ github.ref }}
                  fetchDepth: "1"
                  githubPrivateKey: ${{ secrets.GIT_GITHUB_APP_PEM_FILE }}
                  githubAppId: ${{ secrets.GIT_GITHUB_APP_ID }}
              id: setup-project
            - name: Provision templates
              uses: backbase-common/gc-ai-workflows/provision-python-project@main
              with:
                  githubToken: ${{ steps.setup-project.outputs.githubToken }}
                  packageName: ${{ github.event.repository.name }}
```

> \[!TIP]
> See the [Configurations](/agentic-ai/ci-cd-workflows/configurations) page for complete setup instructions and required secrets.

## Configuration

### Required secrets

The workflow requires these secrets:

* `GIT_GITHUB_APP_PEM_FILE`: GitHub App private key
* `GIT_GITHUB_APP_ID`: GitHub App ID

### Workflow conditions

The workflow only runs when:

* `github.run_number == 1`: First workflow run
* `startsWith(github.event.pusher.name, 'gc-tfrw-')`: Pushed by Terraform workflow

## Provisioning steps

### Setup project

The `setup-project` action:

* Authenticates using GitHub App
* Checks out repository code
* Generates GitHub token for subsequent steps
* Sets up project environment

### Provision Python project

The `provision-python-project` action:

* Creates Python package structure
* Sets package name from repository name
* Configures project files
* Baselines version information

## What gets provisioned

The workflow provisions:

* **Package Structure**: Standard Python package layout
* **Configuration Files**: Project configuration files
* **Version Information**: Initial version baseline
* **Project Metadata**: Repository name and metadata

## Best practices

* **Template Usage**: Create repositories from templates for automatic provisioning
* **Secret Configuration**: Ensure GitHub App secrets are configured
* **First Commit**: Push initial commit to develop branch
* **Verification**: Verify provisioning completed successfully

## Troubleshooting

### Workflow not running

If the workflow doesn't run:

1. **Check Run Number**: Ensure it's the first workflow run
2. **Verify Pusher**: Check if pusher name starts with `gc-tfrw-`
3. **Branch Check**: Ensure push is to develop branch
4. **Manual Trigger**: Use workflow\_dispatch if needed

### Provisioning failures

Common issues:

1. **Authentication**: Verify GitHub App credentials
2. **Permissions**: Check repository permissions
3. **Secrets**: Ensure secrets are properly configured
4. **Timeout**: Workflow times out after 10 minutes

## Next steps

* [Learn about PR workflows](/agentic-ai/ci-cd-workflows/pull-request-workflow)
* [Understand build processes](/agentic-ai/ci-cd-workflows/build-publish-workflow)
* [Explore release management](/agentic-ai/ci-cd-workflows/release-workflow)