Custom Source Methods

Custom source method allows you to build sources for SRPM using your own user-defined script. This provides maximum flexibility when generating build sources.

Overview

The custom source method executes a script that generates a spec file and optionally any other files needed to build a source RPM (tarballs, patches, etc.). The script runs in a mock chroot under a non-privileged user (mockbuild) with internet access.

The script cannot be an SRPM itself. If your tool generates an SRPM, you must extract it within the script.

Required Configuration

Only two parameters are required:

Script

The script file content, written in any scripting language. Important:

Specify the shebang properly (e.g., #!/bin/sh for shell scripts)
The interpreter must be available in the chroot (may need to request via builddeps)
Output files go to the current working directory by default

Chroot

The mock chroot where the script executes. Default is fedora-latest-x86_64 (the latest stable or branched Fedora available at build time).

Optional Parameters

builddeps

Space-separated list of packages pre-installed into the build chroot before script execution.

--script-builddeps "git python3-setuptools rpmdevtools"

resultdir

Directory where the script generates output. Defaults to current working directory.

--script-resultdir results

Environment Variables

Copr defines these environment variables for your script:

Variable	Description	Example
`COPR_OWNER`	Owner of the project (user or group)	`@copr` or `username`
`COPR_PROJECT`	Name of the project	`my-project`
`COPR_PACKAGE`	Name of the package being built	`my-package`
`COPR_RESULTDIR`	Output directory (see `resultdir` parameter)	`/builddir/results`

Script Requirements

The script executes under a non-privileged user (mockbuild). You cannot install RPM packages from within the script - declare them in builddeps instead.

Your script must generate:

Spec file (required)
Source archives referenced by Source statements (typically tarballs)
Patches referenced by Patch statements (optional)

All files should be placed in the resultdir directory.

Extracting Existing SRPMs

If your tool generates an SRPM, extract it within the script:

#!/bin/sh -xe
git clone example.com/foo.git && cd foo
make srpm
bsdtar xf *.src.rpm -C "$COPR_RESULTDIR"

Examples

Simple Spec File Download

#!/bin/sh -x
curl https://praiskup.fedorapeople.org/quick-package.spec -O

Using SRPM Source

#!/bin/sh -x
make dist-srpm
rpmdev-extract redhat/rpm/SRPMS/quick-package-*.src.rpm
mv quick-package*src/* ./

Python Package with Git Submodules

A more complex example showing git cloning, tarball generation, and dynamic versioning:

#!/bin/sh

mkdir -p results
resultdir=$(readlink -f results)

set -x # verbose output
set -e # fail on any error

# Obtain the source code
git clone https://github.com/praiskup/resalloc --recursive --depth 1
cd resalloc

# 1. Generate source tarball into resultdir
python setup.py sdist -d "$resultdir"

# 2. Copy spec file and modify release number
cd rpm
release='~'$(date +"%Y%m%d_%H%M%S")
sed "s/\(^Release:[[:space:]]*[[:digit:]\+]\)/\1$release/" resalloc.spec \
    > "$resultdir"/resalloc.spec

# 3. Copy other sources
cp *.service "$resultdir"

Show CLI Configuration

copr add-package-custom PROJECT \
        --name resalloc \
        --script script \
        --script-resultdir results \
        --script-builddeps 'git' \
        --script-chroot fedora-rawhide-x86_64

copr build-package --name resalloc PROJECT

Webhook Support

Custom source method supports custom webhooks. Unlike other methods, the custom method doesn’t parse webhook payloads automatically - that’s your responsibility.

Hook Payload

When a webhook triggers a build, the payload is dumped to $PWD/hook_payload file. Your script must:

Read and parse the hook_payload file
Determine what to build based on the payload
Generate appropriate sources

Show Example: GitLab Merge Request

When a GitLab merge request event triggers the webhook:

The hook_payload file contains JSON describing the merge request
Your script should parse it to detect the contributor’s fork URL
Clone from the contributor’s repository instead of the main one

#!/bin/sh -e

if [ -f hook_payload ]; then
    # Parse webhook payload to get fork URL
    REPO=$(jq -r '.object_attributes.source.git_http_url' hook_payload)
else
    # Default repository
    REPO="https://gitlab.com/owner/repo.git"
fi

git clone "$REPO"
# ... rest of source generation

It’s valid to trigger custom webhooks without any payload:

curl -X POST <THE_CUSTOM_HOOK_URL>

Best Practices

Use set -e to fail fast on errors
Use set -x for verbose output to aid debugging
Specify absolute paths or use $COPR_RESULTDIR for output
Test locally in a mock chroot before deploying
Keep scripts portable - avoid root-requiring operations
Declare all dependencies in builddeps parameter

Limitations

No root access: Scripts run as mockbuild user
No package installation: Use builddeps to declare required packages
Internet required: Most scripts need network access for cloning/downloading
Build timeout: Scripts must complete within project timeout limits

Advanced Use Cases

For more complex CI/CD workflows with custom source methods, see this blog post about CI/CD with Copr.

Get Started

User Guide

CLI Tool

Advanced

Custom Source Methods

Overview

Required Configuration

Script

Chroot

Optional Parameters

Environment Variables

Script Requirements

Extracting Existing SRPMs

Examples

Simple Spec File Download

Using SRPM Source

Python Package with Git Submodules

Webhook Support

Hook Payload

Best Practices

Limitations

Advanced Use Cases

Build docs developers (and LLMs) love

Get Started

User Guide

CLI Tool

Advanced

​Overview

​Required Configuration

​Script

​Chroot

​Optional Parameters

​Environment Variables

​Script Requirements

​Extracting Existing SRPMs

​Examples

​Simple Spec File Download

​Using SRPM Source

​Python Package with Git Submodules

​Webhook Support

​Hook Payload

​Best Practices

​Limitations

​Advanced Use Cases

Build docs developers (and LLMs) love

Overview

Required Configuration

Script

Chroot

Optional Parameters

Environment Variables

Script Requirements

Extracting Existing SRPMs

Examples

Simple Spec File Download

Using SRPM Source

Python Package with Git Submodules

Webhook Support

Hook Payload

Best Practices

Limitations

Advanced Use Cases