> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.itential.com/itential-gateway/5/git-repositories/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.itential.com/_mcp/server.

# Git repositories in Gateway

> Learn how to create and manage Git repository references in Gateway.

A repository in Gateway is a reference to a Git repository that contains your scripts, automations, or other files. Gateway pulls the repository when you run a service to ensure your scripts are always up to date.

## Public and private repositories

Gateway supports both public and private Git repositories:

* **Public repositories**: No authentication required. Gateway can clone these repositories without credentials.
* **Private repositories**: Require authentication using either SSH keys or HTTP basic authentication (username and password/token).

For information about setting up authentication, see:

* [Use SSH keys to clone Git repositories](./clone-git-repositories-ssh)
* [Configure private repository access](./configure-private-repository-access)

## Create a repository

Use the `iagctl create repository` command to create a repository reference.

For more information, see the [create repository](./iagctl/create-repository) command reference.

### Create a public repository

**Syntax**:

```bash
iagctl create repository <repository-name> \
  --url <git-url>
```

**Example**:

```bash
iagctl create repository my-public-repo \
  --url https://github.com/example/public-automations.git
```

### Create a private repository with SSH authentication

**Syntax**:

```bash
iagctl create repository <repository-name> \
  --url <ssh-git-url> \
  --private-key-name <secret-name>
```

**Parameters**:

* `<repository-name>`: A unique name for the repository reference
* `--url`: The SSH Git URL (starts with git@)
* `--private-key-name`: The name of the secret that contains your SSH private key

**Example**:

```bash
iagctl create repository my-private-repo \
  --url git@github.com:example/private-automations.git \
  --private-key-name git-key
```

For detailed setup instructions, see [Use SSH keys to clone Git repositories](./clone-git-repositories-ssh).

### Create a private repository with HTTP basic authentication

**Syntax**:

```bash
iagctl create repository <repository-name> \
  --url <https-git-url> \
  --username <git-username> \
  --password-name <secret-name>
```

**Parameters**:

* `<repository-name>`: A unique name for the repository reference
* `--url`: The HTTPS Git URL
* `--username`: Your Git username
* `--password-name`: The name of the secret that contains your password or token

**Example**:

```bash
iagctl create repository my-private-repo \
  --url https://github.com/example/private-automations.git \
  --username myusername \
  --password-name github-token
```

For detailed setup instructions, see [Configure access to private repositories](./configure-private-repository-access).

## Reference a specific branch or commit

By default, Gateway clones the default branch of your repository. You can specify a different branch, tag, or commit using the `--reference` parameter.

**Syntax**:

```bash
iagctl create repository <repository-name> \
  --url <git-url> \
  --reference <branch-tag-or-commit>
```

**Examples**:

Create a repository that references the develop branch:

```bash
iagctl create repository my-dev-repo \
  --url https://github.com/example/automations.git \
  --reference develop
```

Create a repository that references a specific tag:

```bash
iagctl create repository my-stable-repo \
  --url https://github.com/example/automations.git \
  --reference v1.2.0
```

## Add tags and descriptions to repositories

You can add tags and descriptions to help organize and identify repositories.

**Example**:

```bash
iagctl create repository automation-repo \
  --url https://github.com/example/automations.git \
  --description "Production automation scripts" \
  --tags "production,automation,networking"
```

## Repository structure best practices

When you organize scripts in a Git repository for use with Gateway, consider these practices:

* **Use clear directory structures**: Organize scripts by type, function, or environment (for example, `scripts/backup/`, `scripts/deployment/`)
* **Keep related files together**: Place scripts and their dependencies in the same directory
* **Use consistent naming**: Name directories and files descriptively
* **Document your structure**: Include a README file that explains the repository organization

Example repository structure:

```text
automation-repo/
├── README.md
├── backup/
│   ├── daily-backup.sh
│   └── weekly-backup.sh
├── deployment/
│   ├── deploy-app.py
│   └── rollback.py
└── monitoring/
    ├── check-status.sh
    └── alert.py
```

When you create a service, you specify the `--working-dir` parameter to tell Gateway which directory contains your script.

## Manage repositories

List all repositories:

```bash
iagctl get repositories
```

View details of a specific repository:

```bash
iagctl describe repository <repository-name>
```

Delete a repository:

```bash
iagctl delete repository <repository-name>
```

Before you delete a repository, verify that no services reference it. If services use the repository, they will fail when you delete it.

> Learn how to create and manage Git repository references in Gateway.