GCP Artifact Registry — SKILL.md

---
name: "GCP Artifact Registry"
description: "Skill for GCP Artifact Registry — auto-generated from documentation"
version: "1.0.0"
author: "skynet"
category: "infrastructure"
agents: ["claude-code", "codex", "gemini"]
tags: ["gcp-artifact-registry", "infrastructure", "auto-generated"]
---

# GCP Artifact Registry

---
name: "GCP Artifact Registry"
description: "Use when you need to store, manage, and secure container images and language packages in Google Cloud. Essential for CI/CD pipelines, multi-region deployments, and artifact lifecycle management."
metadata:
  author: "skynet"
  version: "1.0.0"
category: "infrastructure"
---

# GCP Artifact Registry

## Overview
Google Cloud Artifact Registry is a fully managed service for storing and managing build artifacts including Docker container images, Maven and npm packages, and other dependencies.

## Prerequisites
- Google Cloud CLI installed and authenticated
- Project with Artifact Registry API enabled
- Appropriate IAM permissions (roles/artifactregistry.admin or roles/artifactregistry.writer)

## Core Concepts
- **Repository**: Container for artifacts of a specific format
- **Format**: Type of artifacts (Docker, Maven, npm, Python, etc.)
- **Location**: Regional or multi-regional storage
- **Artifact**: Individual package or image stored in repository

## Essential Commands

### Repository Management

#### Create Repository
```bash
# Docker repository
gcloud artifacts repositories create REPO_NAME \
    --repository-format=docker \
    --location=LOCATION \
    --description="Description"

# Maven repository
gcloud artifacts repositories create maven-repo \
    --repository-format=maven \
    --location=us-central1
```

#### List Repositories
```bash
gcloud artifacts repositories list
gcloud artifacts repositories list --location=us-central1
```

#### Delete Repository
```bash
gcloud artifacts repositories delete REPO_NAME --location=LOCATION
```

### Docker Image Operations

#### Configure Docker Authentication
```bash
gcloud auth configure-docker LOCATION-docker.pkg.dev
```

#### Tag and Push Images
```bash
# Tag image
docker tag SOURCE_IMAGE LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/IMAGE_NAME:TAG

# Push image
docker push LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/IMAGE_NAME:TAG
```

#### Pull Images
```bash
docker pull LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/IMAGE_NAME:TAG
```

### Package Management

#### Maven Configuration
Add to `pom.xml`:
```xml
<distributionManagement>
    <repository>
        <id>artifact-registry</id>
        <url>artifactregistry://LOCATION-maven.pkg.dev/PROJECT_ID/REPO_NAME</url>
    </repository>
</distributionManagement>
```

#### npm Configuration
```bash
# Set registry
npm config set registry https://LOCATION-npm.pkg.dev/PROJECT_ID/REPO_NAME/

# Authenticate
npx google-artifactregistry-auth
```

#### Python Package Setup
```bash
# Configure pip
pip config set global.index-url https://LOCATION-python.pkg.dev/PROJECT_ID/REPO_NAME/simple/

# Install package
pip install PACKAGE_NAME
```

## Decision Trees

### Choosing Repository Location
```
Multi-region needed?
├─ YES: Use multi-region (us, eu, asia)
└─ NO: Single region needed?
   ├─ Low latency required: Choose closest region
   └─ Cost optimization: Choose cheapest region
```

### Repository Format Selection
```
What artifact type?
├─ Container images → docker
├─ Java packages → maven
├─ JavaScript packages → npm
├─ Python packages → python
└─ Generic files → generic
```

## Common Workflows

### CI/CD Pipeline Integration
```bash
#!/bin/bash
# Build and push in CI/CD
PROJECT_ID="your-project"
REPO_NAME="app-repo"
LOCATION="us-central1"
IMAGE_NAME="myapp"
TAG="${GITHUB_SHA:0:7}"

# Build image
docker build -t $IMAGE_NAME:$TAG .

# Tag for registry
docker tag $IMAGE_NAME:$TAG \
    $LOCATION-docker.pkg.dev/$PROJECT_ID/$REPO_NAME/$IMAGE_NAME:$TAG

# Push image
docker push $LOCATION-docker.pkg.dev/$PROJECT_ID/$REPO_NAME/$IMAGE_NAME:$TAG
```

### Cleanup Old Artifacts
```bash
# Delete images older than 30 days
gcloud artifacts docker images list \
    --repository=REPO_NAME \
    --location=LOCATION \
    --filter="createTime<'-P30D'" \
    --format="value(package)" | \
xargs -I {} gcloud artifacts docker images delete {} --quiet
```

### Cross-Project Access
```bash
# Grant access to service account from another project
gcloud artifacts repositories add-iam-policy-binding REPO_NAME \
    --location=LOCATION \
    --member="serviceAccount:SA_EMAIL" \
    --role="roles/artifactregistry.reader"
```

## Security and Access Control

### IAM Roles
```bash
# Grant reader access
gcloud artifacts repositories add-iam-policy-binding REPO_NAME \
    --location=LOCATION \
    --member="user:email@domain.com" \
    --role="roles/artifactregistry.reader"

# Grant writer access
gcloud artifacts repositories add-iam-policy-binding REPO_NAME \
    --location=LOCATION \
    --member="group:developers@company.com" \
    --role="roles/artifactregistry.writer"
```

### Service Account Key Setup
```bash
# Create service account
gcloud iam service-accounts create artifact-registry-sa

# Grant permissions
gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:artifact-registry-sa@PROJECT_ID.iam.gserviceaccount.com" \
    --role="roles/artifactregistry.writer"

# Create and download key
gcloud iam service-accounts keys create key.json \
    --iam-account=artifact-registry-sa@PROJECT_ID.iam.gserviceaccount.com
```

## Monitoring and Management

### View Repository Details
```bash
gcloud artifacts repositories describe REPO_NAME --location=LOCATION
```

### List Artifacts
```bash
# List Docker images
gcloud artifacts docker images list --repository=REPO_NAME --location=LOCATION

# List packages
gcloud artifacts packages list --repository=REPO_NAME --location=LOCATION
```

### Vulnerability Scanning
```bash
# Enable scanning
gcloud container images scan IMAGE_URL

# View scan results
gcloud container images describe IMAGE_URL --show-package-vulnerability
```

## Troubleshooting

### Authentication Issues
**Error**: `unauthorized: You don't have the needed permissions`
```bash
# Check authentication
gcloud auth list
gcloud auth application-default login

# Configure Docker
gcloud auth configure-docker LOCATION-docker.pkg.dev
```

### Permission Denied
**Error**: `Permission "artifactregistry.repositories.uploadArtifacts" denied`
```bash
# Check IAM bindings
gcloud artifacts repositories get-iam-policy REPO_NAME --location=LOCATION

# Add required role
gcloud artifacts repositories add-iam-policy-binding REPO_NAME \
    --location=LOCATION \
    --member="user:$(gcloud config get-value account)" \
    --role="roles/artifactregistry.writer"
```

### Repository Not Found
**Error**: `Repository not found`
```bash
# Verify repository exists
gcloud artifacts repositories list --location=LOCATION

# Check location spelling
gcloud artifacts locations list
```

### Docker Push Fails
**Error**: `denied: Token exchange failed for project`
```bash
# Re-authenticate
gcloud auth login
gcloud auth configure-docker LOCATION-docker.pkg.dev

# Check project ID
gcloud config get-value project
```

### Network Connectivity Issues
```bash
# Test connectivity
curl -I https://LOCATION-docker.pkg.dev

# Check firewall rules
gcloud compute firewall-rules list --filter="direction:EGRESS"
```

## Best Practices
- Use regional repositories for better performance
- Implement artifact retention policies
- Enable vulnerability scanning for container images
- Use least privilege IAM roles
- Tag images with semantic versioning
- Automate cleanup of old artifacts
- Monitor storage costs and usage