Quay Tag Parameter

A Jenkins plugin that integrates with Quay.io (or any private Quay registry) to fetch and select Docker image tags from Quay repositories. Supports both Freestyle jobs (via build parameters) and Pipeline jobs (via the quayImage step).

• Build Parameter: Dropdown selection of Quay.io image tags in job configuration
• Pipeline Step: quayImage() step for fetching image references in Jenkinsfiles
• Custom Quay Endpoint: Connect to quay.io or any private/on-premise Quay registry (e.g., quay.mycompany.com)
• Public & Private Repos: Support for both public repositories and private repos via robot tokens
• Dynamic Tag Fetching: Real-time tag updates via AJAX
• Caching: 5-minute cache for API responses to reduce load
• Secure: Uses Jenkins Credentials API, tokens are never exposed in logs

1. Go to Manage Jenkins > Credentials
2. Add a new credential:
   • Kind: Secret text
   • Secret: Your Quay.io robot token
   • ID: e.g., quay-robot-token
   • Description: Quay.io Robot Token

1. Log in to quay.io (or your private Quay registry)
2. Go to your organization > Robot Accounts
3. Create a new robot account
4. Grant read access to your repository
5. Copy the robot token

1. Create or configure a Freestyle job

2. Check This project is parameterized

3. Add parameter > Quay.io Image Parameter

4. Configure:

   • Name: QUAY_IMAGE (or any name)
   • Quay Endpoint: Registry hostname (default: quay.io, or use quay.mycompany.com for private registries)
   • Organization: Your Quay org (e.g., mycompany)
   • Repository: Repository name (e.g., myapp)
   • Credentials: Select your robot token (optional for public repos)
   • Tag Limit: Number of tags to show (default: 20)
   • Default Tag: Fallback tag (default: latest)

5. Click Test Connection to verify

During the build, these environment variables are available:

pipeline {
    agent any
    stages {
        stage('Get Image') {
            steps {
                script {
                    def imageRef = quayImage(
                        organization: 'my-org',
                        repository: 'my-repo',
                        credentialsId: 'quay-robot-token'
                    )
                    echo "Using image: ${imageRef}"
                    // Output: quay.io/my-org/my-repo:latest-tag-name
                }
            }
        }
    }
}

def imageRef = quayImage(
    organization: 'my-org',
    repository: 'my-repo',
    tag: 'v1.0.0'
)
// Output: quay.io/my-org/my-repo:v1.0.0

def imageRef = quayImage(
    organization: 'my-org',
    repository: 'my-repo',
    quayEndpoint: 'quay.mycompany.com',
    credentialsId: 'quay-robot-token',
    tag: 'v1.0.0'
)
// Output: quay.mycompany.com/my-org/my-repo:v1.0.0

def tags = quayImage(
    organization: 'my-org',
    repository: 'my-repo',
    listTags: true,
    tagLimit: 10
)

tags.each { tag ->
    echo "Available tag: ${tag}"
}

def imageRef = quayImage(
    organization: 'coreos',
    repository: 'etcd'
)

pipeline {
    agent any
    parameters {
        quayImageParameter(
            name: 'DEPLOY_IMAGE',
            description: 'Select image to deploy',
            quayEndpoint: 'quay.io',       // optional, defaults to quay.io
            organization: 'mycompany',
            repository: 'myapp',
            credentialsId: 'quay-robot-token',
            tagLimit: 20,
            defaultTag: 'latest'
        )
    }
    stages {
        stage('Deploy') {
            steps {
                echo "Deploying: ${params.DEPLOY_IMAGE}"
                sh "docker pull ${params.DEPLOY_IMAGE}"
            }
        }
    }
}

Returns:

• If listTags=false: String with full image reference (e.g., quay.io/org/repo:tag or quay.mycompany.com/org/repo:tag)
• If listTags=true: String array of tag names

• Verify your robot token is correct
• Check the token hasn't expired
• Ensure the credential is a "Secret text" type

• Verify the robot account has read access to the repository
• Check the organization and repository names are correct

• Verify the organization name (case-sensitive)
• Verify the repository name
• For private repos, ensure credentials are configured

• Wait a few minutes and try again
• Quay.io has API rate limits

• Tags are cached for 5 minutes to reduce API calls
• Use the Test Connection button to fetch fresh data

• API tokens are stored using Jenkins Credentials API
• Tokens are never logged or exposed in build output
• All API calls use HTTPS
• Custom endpoints are normalized (protocol stripped, trailing slashes removed)
• Input validation prevents injection attacks

See CONTRIBUTING.md for development setup and guidelines.

MIT License - see LICENSE file for details.