apple/pass-builder

Requirements

• Swift 6.3+
• macOS 14+ or Linux

Installation

Add Pass Builder to your Package.swift:

dependencies: [
    .package(url: "https://github.com/apple/PassBuilder.git", from: "0.1.0")
]

Then add the library to your target's dependencies:

.target(
    name: "MyApp",
    dependencies: [
        .product(name: "PassBuilder", package: "PassBuilder")
    ]
)

Usage

Import a Pass Designer template

Load a .pkpasstemplate bundle created in Pass Designer:

import PassBuilder

let templateURL = URL(filePath: "/path/to/MyPass.pkpasstemplate")
let myPass = try PassPackage(url: templateURL)

// Customize the imported pass as needed
myPass.pass.serialNumber = "unique-serial-number"

Sign a pass

Sign a pass directory with your certificates to produce a distributable .pkpass file:

let passCertificate = try PassCertificate(
    url: URL(filePath: "/path/to/pass-certificate.p12"),
    password: "certificate-password"
)

let wwdrCertificate = try PassCertificate(
    url: URL(filePath: "/path/to/wwdr-certificate.cer")
)

let signer = PassSigner(
    passCertificate: passCertificate,
    wwdrCertificate: wwdrCertificate
)

try await signer.signPass(
    myPass,
    destination: URL(filePath: "/path/to/MyPass.pkpass")
)

Validate a pass

let validator = PassValidator()
let result = validator.validate(myPass)

for issue in result.issues {
    print(issue)
}

Command-line tool

Pass Builder includes buildpass, a command-line tool for working with passes.

Personalize a template

Apply a protobuf personalization payload to a pass template:

buildpass personalize /path/to/template.pkpasstemplate \
    --protobuf /path/to/personalization.pb \
    --output /path/to/PersonalizedPass.pass

Sign a pass

buildpass sign /path/to/MyPass.pass \
    --pass-certificate /path/to/certificate.p12 \
    --wwdr-certificate /path/to/wwdr.cer

Provide the certificate password through the BUILDPASS_PASS_CERTIFICATE_PASSWORD environment variable. If you don't set it, buildpass prompts you interactively.

Validate a pass

buildpass validate /path/to/MyPass.pass

Certificates

To sign passes, you need:

1. Pass Type ID certificate — A .p12 certificate registered in Apple Developer Portal under Certificates, Identifiers & Profiles. This certificate must match the passTypeIdentifier in your pass.
2. WWDR intermediate certificate — The Apple Worldwide Developer Relations (WWDR) certificate, available from the Apple Certificate Authority.

Contributing

Your contributions help shape the future of Pass Builder! We welcome contributors of all backgrounds and experience levels, recognizing that diverse perspectives drive better outcomes for everyone.

How you can help

• Reporting bugs with clear, reproducible steps as GitHub Issues
• Improving documentation to make the project more accessible
• Triaging Issues by providing feedback, testing, and validation

We are not accepting pull requests for new enhancements and tests at launch while we learn how the community uses this project.

Package Metadata

Repository: apple/pass-builder

Default branch: main

README: README.md