Contents¶

Before going into the overall picture, one should realize that most of the components listed above are optional.

Here is a diagram representing pagure without all the optional components:

And here is a diagram of all the components together: .SS Pagure core application

The core application is the flask application interacting with gitolite to provide a web UI to the git repositories as well as tickets and pull-requests. This is the main application for the forge.

Pagure workers¶

The communication between the core application and its worker is based on celery and defaults to using redis but any of the queueing system supported by celery could be used instead.

Gitolite¶

Pagure supports cloning over both ssh and http, but writing can only be done via ssh, through gitolite.

Pagure doc server¶

Pagure can be run just fine without the doc server, all you need to do is to not define the variable DOC_APP_URL in the configuration file.

Pagure milter¶

In the case of pagure, the milter is used to allow replying on a comment of a ticket or a pull-request by directly replying to the notification sent. No need to go to the page anymore to reply to a comment someone made.

The milter integrates with a MTA such as postfix or sendmail that you will have running and have access to in order to change its configuration.

Pagure EventSource Server¶

For pagure this technology is used to allow live-refreshing of a page when someone is viewing it. For example, while you are reading a ticket if someone comments on it, the comment will automatically show up on the page without the need for you to reload the entire page.

The flow is: the main pagure server does an action, sends a message over redis, the eventsource server picks it up and send it to the browsers waiting for it, then javascript code is executed to refresh the page based on the information received.

Pagure web-hook Server¶

This is the second notifications system in pagure with fedmsg. These notifications are running on their own service to prevent blocking the main web application in case the third part service is timing-out or just being slow.

The flow is: the main pagure server does an action, sends a message over redis, the web-hook server picks it up, build the query and performs the POST request to the specified URLs.

Pagure load JSON service¶

Pagure log com service¶

First Steps on pagure¶

Login to pagure or create your account¶

For instances of pagure such as the one at pagure.io where the authentication is delegated to a third party (in the case of pagure.io, the Fedora Account System) via OpenID, the local user account is created upon login.

This means, you cannot be added to a group or a project before you login for the first time as the system will simply not know you.

If you run your own pagure instance which uses the local authentication system, then you will find on the login page an option to create a new account.

Upload your SSH key¶

An ssh key is composed of two parts:

If you have never generated a ssh key, you can do so by running:

ssh-keygen

or alternatively on GNOME using the application seahorse.

This will create two files in ~/.ssh/ (~ is the symbol for your home folder).

These two files will be named (for example) id_rsa and id_rsa.pub. The first one is the private key that must never be shared. The second is the public key that can be uploaded on pagure to give you ssh access.

To upload your public key onto pagure:

1. Login into pagure and click on the user icon on the top right corner, there, select My settings.

2. In the authentication section of your user settings copy the content of your id_rsa.pub file in the Public SSH key text box and save your ssh key settings. .sp NOTE:

Configure the default email address¶

The settings page of your account (see above for how to access the page) allows you to add multiple email addresses and set one as default.

Your default email address is the address that will be used to send you notifications and also as the email address in the git commit if you merge a pull-request with a merge commit.

For online editing, when doing the commit, you will be presented with the list of valid email addresses associated with your account and you will be able to choose which one you wish to use.

NOTE:

Forks¶

You can see a list of projects you've forked on your home page.

Create a Fork on Pagure¶

Configure your Local Git Repository¶

$ git clone ssh://git@pagure.io/forks/jcline/pagure.git
$ cd pagure

After cloning your fork locally, it's a good idea to add the upstream repository as a git remote. For example:

$ git remote add -f upstream ssh://git@pagure.io/pagure.git

This lets you pull in changes that the upstream repository makes after you forked. Consult Git's documentation for more details.

Pushing Changes¶

$ git checkout -b my-feature-or-bugfix

It's a good idea to give the branch a descriptive name so you can find it later. Next, make your changes. Once you're satisfied, add the changes to Git's staging area and commit the changes:

$ git add -A  # add all changes
$ git commit -s # prepare changes for upload

Your text editor of choice will open and you can write your commit message. If you have not done so already upload-your-ssh-key now. Afterwards, you are ready to push your changes to your remote fork:

$ git push -u origin my-feature-or-bugfix # upload changes

In case you cloned the repo via HTTP, for example using a command like git clone https://..., the push will fail. Pagure.io does not support pushing over HTTP. An easy workaround is to use:

$ git push -u origin my-feature-or-bugfix ssh://git@pagure.io/forks/jcline/pagure.git

You are now ready to open-pull-request.

Understanding Read Only Mode of projects¶

In Pagure, we use gitolite for Access Control Lists when using SSH. Modifying gitolite may be a time taking task (depending on number of projects hosted on the pagure instance) that's why Pagure does it outside of HTTP Request-Response Cycle.

Whenever you fork a project or add/remove a new user/group to project, gitolite needs to be refreshed in order to put those changes in effect for ssh based git usage.

Actions that put the project in read only mode¶

HTTP PUSH¶

Git push over http with API token¶

Once the API token has been generate, the user needs to enter it with git prompts for a password (instead of their actual password).

For example:

$ git push
username: pingou
password: ABC123...

Git push over http with Username & Password¶

For these pagure instances and for these only, when being prompted by git for an username and password the user can choose to enter either their username and actual password or their username and an API token.

Storing the password/token¶

You can use two modes for the store, either cache or store. - cache will cache your credential in memory for 15 minutes (by default) - store will actually store your credentials in plain text on disk

You can set this using either:

$ git config credential.helper store
$ git config credential.helper cache

The timeout of the cache can be configured using:

$ git config credential.helper 'cache --timeout=3600'

Where the timeout value is a number of seconds (so here the cache is extended to one hour).

Finally, if you wish to use this configuration on multiple project, you can add the --global argument to these commands which will make the configuration work for all your git repo instead of just the one in which you run the command.

Pull Requests¶

Open a Pull Request¶

Pagure to Pagure pull request¶

From the project overview¶

Notes: The New PR button appears only if there are commits not available in the main branch. .SS From the commits history

You can create a pull request from another git hosting platform (e.g. GitHub, GitLab). This is a remote pull request.

From the pull requests list¶

Congratulations! It is now up to the project maintainer to accept your changes by merging them.

Updating Your Pull Request¶

Adding to your pull request is as simple as pushing new commits to the branch you used to create the pull request. These will automatically be displayed in the commit list for the pull request.

Rebasing¶

Working with Pull Requests¶

git fetch $REMOTE pull/$PR_NUMBER/head:$BRANCHNAME

For example, if you have PR#1 which "adds support for foo" you might run:

git fetch origin pull/1/head:add-foo-support

Then you can work with the add-foo-support normally:

git checkout add-foo-support

NOTE:

If you want to allow working with all of your pull requests locally, you can do so by editing your git configuration as follows. Locate your remote in the .git/config file, for example:

[remote "origin"]
    url = ssh://git@pagure.io/pagure.git
    fetch = +refs/heads/*:refs/remotes/origin/*

Now add this line:

fetch = +refs/pull/*/head:refs/remotes/origin/pr/*

to that section as the first fetch line, like this:

[remote "origin"]
    url = ssh://git@pagure.io/pagure.git
    fetch = +refs/pull/*/head:refs/remotes/origin/pr/*
    fetch = +refs/heads/*:refs/remotes/origin/*

Obviously, the remote URL should be matching the URL of your project (pagure project in this example).

Now you can fetch the all the pull requests:

$ git fetch origin
From ssh://pagure.io/pagure
* [new ref]        refs/pull/2541/head -> origin/pr/2541
* [new ref]        refs/pull/2540/head -> origin/pr/2540
* [new ref]        refs/pull/2538/head -> origin/pr/2538

To checkout a particular pull request:

$ git checkout pr/25413
Branch pr/2541 set up to track remote branch pr/2541 from origin.
Switched to a new branch 'pr/2541'

You will now be able to use this branch to work from or on this pull requests.

If you are only interested in one particular pull request and do not want to fetch all the project PRs, you can add to your ~/.bashrc the following function:

function pullpr {
    remote="${2:-origin}"
    git fetch $remote pull/$1/head:pr_$1
    git checkout pr_$1
}

Then after sourcing your ~/.bashrc or restarting your shell, you can use the pullpr function to checkout a pull request from within the clone of the git repository. For example checkout pull request number 58 from current git clone (here the infra-docs project)

$ source ~/.bashrc
$ pullpr 58
remote: Counting objects: 393, done.
remote: Compressing objects: 100% (238/238), done.
remote: Total 365 (delta 231), reused 255 (delta 127)
Receiving objects: 100% (365/365), 71.36 KiB | 63.00 KiB/s, done.
Resolving deltas: 100% (231/231), completed with 20 local objects.
From ssh://pagure.io/infra-docs
* [new ref]         refs/pull/58/head -> pr_58
Switched to branch 'pr_58'

Using Markdown in Pagure¶

Pagure relies on the Markdown python module to do the conversion. It has enabled a few extensions:

README files can also rely on:

While comments use:

WARNING:

Styling¶

Quoting¶

Before merging this pull request, remember Clark Kent mentioned this:
> Double-check there's no reference to the Kryptonite library in the program since we removed that a few versions ago.

Before merging this pull request, remember Clark Kent mentioned this:

You can also make a line-wrapping blockquote using <br/>.

Remember what Solomon said:
> I don't want to survive. <br/> I want to live.

Remember what Solomon said:

For more details regarding Blockquote, refer Blockquote.

Code¶

When running the program for the first time, use `superman --initialize`.

When running the program for the first time, use superman --initialize.

To format multiple lines of code into its own block, you can wrap the text block with four tilde (~) characters

Install the needed system libraries:
`~~~~`
sudo dnf install git python-virtualenv libgit2-devel \
                libjpeg-devel gcc libffi-devel redhat-rpm-config
`~~~~`

Install the needed system libraries:

sudo dnf install git python-virtualenv libgit2-devel \
             libjpeg-devel gcc libffi-devel redhat-rpm-config

Hyperlinks¶

Regular links¶

Pagure is used by the [Fedora Project](https://fedoraproject.org).

Pagure is used by the Fedora Project.

Links to ticket/PR of the same project¶

This is an example for #2921

This is an example for #2921

Links to ticket/PR of another project¶

This is an example for pagure#2921

This is an example for pagure#2921

Lists¶

Unordered lists¶

* Superman
* Batman
    * Protector of Gotham City!
* Superwoman
* Harley Quinn
    * Something on this list is unlike the others...

Ordered lists¶

1. Superman
2. Batman
    1. Protector of Gotham City!
    2. He drives the Batmobile!
3. Superwoman
4. Harley Quinn
    1. Something on this list is unlike the others...
    2. Somebody evil lurks on this list!

Tagging users¶

@jflory7, could you please review this pull request and leave feedback?

@jflory7, could you please review this pull request and leave feedback?

Tagging issues or pull requests¶

If you need to tag an issue or pull request that is outside of the current project, you are also able to do this. For cross-projects links, you can tag them by typing <project name>#id or <username>/<project name>#id.

Emoji¶

I reviewed the PR and it looks good to me. :+1: Good to merge! :clapper:

I reviewed the PR and it looks good to me. 👍 Good to merge! 🎬

Improve this documentation!¶

Project settings¶

This page presents the different settings and there effect.

Always merge¶

When merging a pull-request in pagure there are three states:

If the Always merge option is on, then the fast-forward option above is disabled in favor of the merge option.

Comment editing¶

After commenting on a ticket or a pull-request, the admins of the project and the author of the comment may be allowed to edit the comment. This allows them to adjust the wording or the style as they wish.

NOTE:

Some project may not want to allow editing comments after they were posted and this setting allows turning it on or off.

Enforce signed-off commits in pull-request¶

If this line is missing, pagure will display a message near the Merge button, allowing project admin to request the PR to be updated.

NOTE:

Issue tracker¶

Minimum score to merge pull-request¶

If this option is enabled, anyone can vote in favor or against a pull-request and the sum of the votes in favor minus the sum of the votes against give the pull-request a score that should be equal or greater than the value entered in this option for the pull-request to be allowed to be merged.

NOTE:

To vote in favor of a pull-request, use either: * +1 * :thumbsup:

To vote against a pull-request, use either: * -1 * :thumbsdown:

NOTE:

NOTE:

NOTE:

Only assignee can merge pull-request¶

If this option is enabled, only the person assigned to the pull-request can merge it.

Project documentation¶

This repository is then accessible under the Docs tab in the menu of the project.

If you prefer to store your documentation elsewhere or maybe even within the sources of the project, you can disable the Docs tab by un-checking this option.

Pull requests¶

However, some projects may prefer receiving patches by email on their list or via another hosting platform or simply do not wish to use the pull-request mechanism at all. Un-checking this option will therefore prevent anyone from opening a pull-request against this project.

NOTE:

Web-hooks¶

The URL of the web-hooks can be entered in this field.

NOTE:

Tags¶

Deploy keys¶

Project Level Access Control¶

With Project ACL feature, We can now have three levels of access:

Add/Update Access¶

Points to be noted¶

Using the roadmap feature¶

The principal is as follow:

Example¶

Pagure offers the possibility to flag pull-requests and commits. A flag is a way for a third-party tool to provide feedback on a pull-request or a commit.

This feedback can be as simple as the outcome of running the tests, or some lint tool, or test coverage evolution.

Add a flag¶

Example of two flags on a commit:¶

Magic words are words and constructs you can use in your commit message to make pagure act on tickets or pull-requests.

Enabling magic words¶

Using magic words¶

If using the full URL, it is possible to reference issues in other projects.

The recognized keywords are:

Examples:

Capitalization does not matter; neither does the colon (:) between keyword and number.

Using the doc repository of your project¶

The doc repository is a simple Git repo. It can be displayed as a subfolder of a project or as a dedicated Git repo. Either way its content can be displayed in 2 ways:

By default the Docs tab in the project's menu is disabled, you will have to visit the project's settings page and turn it on in the Project options section.

The URL to clone the doc repo is:

To view the doc source files in the browser:

Different file types can be used for your documentation in this repo:

Updating documentation hosted in a dedicated repo is like using other repos.

Example¶

The built documentation is available at: https://docs.pagure.org/pagure/.

This is how it is built/updated:

git clone https://pagure.io/pagure.git

cd pagure/doc

make html

git clone ssh://git@pagure.io/docs/pagure.git

cp -r _build/html/* pagure/

cd pagure
git add .
git commit -am "Update documentation"
git push

cd ..
rm -rf pagure  # remove the doc repo
rm -rf _build  # remove the output from the sphinx's build

To make things simpler, the following script (name update_doc.sh) can be used:

#!/bin/bash
make html
git clone "ssh://git@pagure.io/docs/$1.git"
cp -r _build/html/* $1/
(
    cd $1
    git add .
    git commit -av
    git push
)
rm -rfI _build
rm -rfI $1

It can be used by running update_doc.sh <project> from within the folder containing the doc.

So for pagure it would be something like:

cd pagure/doc
update_doc.sh pagure

Using web-hooks¶

Activating web-hooks notifications¶

Pagure will send a notification to this/these URL(s) for every action made on this project: new issue, new pull-request, new comments, new commits...

NOTE:

Authenticating the notifications¶

Each POST request made contains some specific headers:

X-Pagure
X-Pagure-Project
X-Pagure-Signature
X-Pagure-Signature-256
X-Pagure-Topic

X-Pagure contains URL of the pagure instance sending this notification.

X-Pagure-Project contains the name of the project on that pagure instance.

X-Pagure-Signature contains the signature of the message allowing to check that the message comes from pagure.

X-Pagure-Signature-256 contains the SHA-256 signature of the message allowing to check that the message comes from pagure.

NOTE:

X-Pagure-Topic is a global header giving a clue about the type of action that just occurred. For example issue.edit.

WARNING:

Pagure relies on hmac to sign the content of its messages. If you want to validate the message, in python, you can do something like the following:

import hmac
import hashlib
payload =  # content you received in the POST request
headers =  # headers of the POST request
project_web_hook_key =  # private web-hook key of the project
hashhex = hmac.new(
    str(project_web_hook_key), payload, hashlib.sha1).hexdigest()
if hashhex != headers.get('X-Pagure-Signature'):
    raise Exception('Message received with an invalid signature')

Templates for ticket input¶

The templates are provided in the git repository containing the meta-data for the tickets. They must be placed under a templates folder in this git repository, end with .md and as the extension suggests can be formatted as markdown.

If you create a template templates/default.md, it will be shown by default when someone ask to create a new ticket.

Example¶

git clone ssh://git@pagure.io/tickets/test.git
cd test

mkdir templates

vim templates/default.md

And place in this file the following content:

##### Issue
##### Steps to reproduce
1.
2.
3.
##### Actual results
##### Expected results

git add templates
git commit -m "Add a default template for tickets"
git push

[1]

The URLs to the different git repositories can be found on the main page of the project, on the right-side menu, under the section Source GIT URLs. Click on more to see them if you are logged in and have access to the repository (the ticket and request git repositories require a commit access or higher).

Customize the PR page¶

The customization is done via a file in the git repository containing the meta-data for the pull-requests. This file must be placed under a templates folder, be named contributing.md and can be formatted as you wish using markdown.

Example¶

git clone ssh://git@pagure.io/requests/test.git
cd test

mkdir templates

vim templates/contributing.md

And place in this file the following content:

Contributing to test
====================
When creating a pull-request against test, there are couple of items to do
that will speed up the review process:
* Ensure the unit-tests are all passing (cf the ``runtests.py`` script at the
  top level of the sources)
* Check if your changes are [pep8](https://www.python.org/dev/peps/pep-0008/)
  compliant for this you can install ``python-pep8`` and run the ``pep8`` CLI
  tool

git add templates
git commit -m "Customize the PR page"
git push

[1]

All the URLs to the different git repositories can be found on the main page of the project, on the right-side menu, under the section Source GIT URLs, click on more to see them.

Theming Guide¶

Setting a theme¶

THEME = "pagureio"

Theme contents¶

templates/¶

WARNING:

static/¶

<link href="{{ url_for('theme.static', filename='theme.css') }}"
      rel="stylesheet" type="text/css" />

templates/theme.html¶

The current items configurable in theme.html are:

masthead_class variable¶

{% set masthead_class = "navbar-dark bg-dark" %}

masthead_navbar_items() macro¶

{% macro masthead_navbar_items() %}
    <li class="nav-item ml-3">
        <a class="nav-link font-weight-bold" href="...">
            Foobar
        </a>
    </li>
{% endmacro %}

site_title variable¶

{% set site_title = "Pagure" %}

projectstring(Bool:plural) macro¶

{% macro projectstring(plural=False) -%}
    {% if plural %}
        Repositories
    {% else %}
        Repository
    {% endif %}
{% endmacro -%}

projecticon variable¶

{% set projecticon = "Package" %}

head_imports() macro¶

{% macro head_imports() %}
    <link rel="shortcut icon" type="image/vnd.microsoft.icon"
          href="{{ url_for('theme.static', filename='favicon.ico')}}"/>
    <link rel="stylesheet" href="{{ url_for('theme.static', filename='bootstrap/bootstrap.min.css')}}" />
    <link href="{{ url_for('theme.static', filename='theme.css') }}" rel="stylesheet" type="text/css" />
{% endmacro %}

js_imports() macro¶

{% macro js_imports() %}
    <script src="{{ url_for('theme.static', filename='bootstrap/bootstrap.bundle.min.js')}}"></script>
{% endmacro %}

browseheader_message(select) macro¶

{% macro browseheader_message(select) %}
    {% if select == 'projects' %}
    <div class="row justify-content-around">
    <div class="col-md-8">
        <div class="jumbotron bg-transparent m-0 py-4 text-center">
            <h1 class="display-5">Welcome to my Pagure</h1>
            <p class="lead">Pagure is an Open Source software code hosting system.</p>
        </div>
    </div>
    </div>
    {% endif %}
{% endmacro %}

footer() macro¶

{% macro footer() %}
    <div class="footer py-3 bg-light border-top text-center">
        <div class="container">
            <p class="text-muted credit">
        Powered by
        <a href="https://pagure.io/pagure">Pagure</a>
        {{ g.version }}
            </p>
            <p><a href="{{ url_for('ui_ns.ssh_hostkey') }}">SSH Hostkey/Fingerprint</a> | <a href="https://docs.pagure.org/pagure/usage/index.html">Documentation</a></p>
        </div>
    </div>
{% endmacro %}

about_page() macro¶

{% macro about_page() %}
    <div class="container mt-5">
        <h1>About</h1>
        <p>This is an instance of Pagure, a git forge.</p>
        <p>If you experience a bug or security concern, please <a href="https://pagure.io/pagure/issues">submit an issue</a>.</p>
        <p>You may also post questions to the Pagure Development list by emailing: <a href="mailto:pagure-devel@lists.pagure.io">pagure-devel@lists.pagure.io</a> or <a href="https://lists.pagure.io/admin/lists/pagure-devel.lists.pagure.io/">subscribe to the list</a>.</p>
        <p><a href="https://lists.pagure.io/admin/lists/pagure-announce.lists.pagure.io/">Subscribe to announcements</a> about Pagure.</p>
    </div>
{% endmacro %}

Upgrade a database¶

To upgrade the database to the latest version simply run:

alembic upgrade head

NOTE:

PAGURE_CONFIG=/path/to/pagure.cfg alembic upgrade head

This may fail for different reasons:

This can be because the version of the database schema saved is incorrect. It can be debugged using the following commands:

alembic current

alembic history

Once the revision at which your database should be is found (in the history) you can declare that your database is at this given revision using:

alembic stamp <revision id>

Eventually, if you do not know where your database is or should be, you can do an iterative process stamping the database for every revision, one by one trying every time to alembic upgrade until it works.

SQLite is handy for development but does not support all the features of a real database server. Upgrading a SQLite database might therefore not work, depending on the changes done.

In some cases, if you are using a SQLite database, you will have to destroy it and create a new one.

Pagure CI¶

NOTE:

Contents:

Jenkins with Pagure-ci¶

This document describe the steps needed to make it work.

How does it work?¶

REPO corresponds to the url of the repository the pull-request originates from (so most often it will be a fork of the main repository).

BRANCH corresponds to the branch the pull-request originates from (the branch of the fork).

BRANCH_TO corresponds to the targeted branch in the main repository (the branch of the main project in which the PR is to be merged).

cause is the reason the build was triggered (ie: the pull-request id or the commit hash).

How to enable Pagure CI¶

These steps will activate the hook, after reloading the page or the tab, you will be given access to two important values: the token used to trigger the build on jenkins and the URL used by jenkins to report the status of the build. Keep these two available when configuring jenkins for your project.

Configure Jenkins¶

Configure your project on Jenkins¶

FORMAT: JSON
PROTOCOL: HTTP
EVENT: All Events
URL: <The URL provided in the Pagure CI hook on pagure>
TIMEOUT: 3000
LOG: 1

Example Script

# Script specific for Pull-Request build
if [ -n "$REPO" -a -n "$BRANCH" ]; then
git remote rm proposed || true
git remote add proposed "$REPO"
git fetch proposed
git checkout origin/master
git config --global user.email "you@example.com"
git config --global user.name "Your Name"
git merge --no-ff "proposed/$BRANCH" -m "Merge PR"
fi
# Part of the script specific to how you run the tests on your project

Tips and tricks¶

To manually trigger a run of pagure-ci on a given pull-request, simply add a comment saying: pretty please pagure-ci rebuild.

NOTE:

NOTE:

Quick replies¶

Examples where this can be handy:

All these requests might be accompanied by a description on why it's requested. With quick replies you can prepare the descriptions and the just use them with a click of a button.

Using quick replies¶

The button is only visible if the project has some quick replies defined.

Additionally, the button will become insensitive when you type something into the comment box or switch to preview. This should avoid writing over your carefully crafted comment by accident. If you remove the text from the field, the button will work again.

Creating and modifying quick replies¶

The order in which you define the replies will be preserved on the chooser menu. This can be used to put the most frequently used ones on the top of the list.

Troubleshooting¶

Contents:

Inaccessible pull-requests¶

The symptoms¶

The branch into which this pull-request was to be merged: XXX seems to
no longer be present in this repo

(Where XXX is a branch name).

(Here XXX is m2).

This means that the pull-request was opened against a branch on your repo and that this branch no longer exists. Pagure is therefore unable to compute the diff between the sources and the target of the pull-request.

The pull-request is thus inaccessible but remains in the list of open pull-requests.

The solution¶

This can be done using git simply by doing:

git checkout -b <branch_name>
git push origin <branch_name>

It will create the branch named <branch_name> in pagure, allowing the diff to be computed for that pull-request and thus allowing it to be displayed. It is then up to you to see if this pull-request is still relevant and should be merged or closed.

Tips and tricks¶

Place image onto your overview page¶

Example¶

![See Copr workflow](/copr/copr/raw/master/f/doc/img/copr-workflow.png)

Text in the square brackets will be used as an alt description.

Pre-fill issue using the URL¶

Example:¶

The above URL will autofill the text boxes for Title and Description field with Title set to <Issue> and Description set to <Issue Content>.

Pre-fill issue template using the URL¶

Example:¶

The above URL will autofill the ticket with the specified template. The TemplateName should be the name of the template file on disk (in the templates directory of the ticket git repository).

Filter for issues not having a certain tag¶

Example:¶

Local user creation without email verification¶

Filter an user's projects by their access¶

You can specify an acl= argument to the URL to filter the list of projects by access.

NOTE:

Examples:¶

Filter issues by (custom) fields¶

This also works for the following regular fields: tags, milestones, author, assignee, status, priority (but tags and milestones despite their name only support a single value).

Examples:¶

Search the comments of issues¶

Examples:¶

Pagure API¶

Installing pagure via RPM¶

Pagure is packaged for Fedora since Fedora 21 and is available for RHEL and its derivative via the EPEL repository <https://fedoraproject.org/wiki/EPEL>. So installing it is as easy as:

dnf install pagure pagure-milters pagure-ev pagure-webhook

or

yum install pagure pagure-milters pagure-ev pagure-webhook

The pagure package contains the core of the application and the doc server. (See the Overview page for a global overview of the structure of the project).

The pagure-milters package contains, as the name says, the milter (a mail filter to hook into a MTA).

The pagure-ev package contains the eventsource server.

The pagure-webhook package contains the web-hook server.

NOTE:

If you wish to run a newer version of pagure than what is in the repositories you can easily rebuild it as RPM.

Simply follow these steps: # Clone the sources:

git clone https://pagure.io/pagure.git

# Go to the folder:

cd pagure

# Build a tarball of the latest version of pagure:

python setup.py sdist

# Build the RPM:

rpmbuild -ta dist/pagure*.tar.gz

This will build pagure from the version present in your clone.

Once, the RPM is installed the services pagure_milter and pagure_ev are ready to be used but the database and the web-application parts still need to be configured.

Installing pagure via setup.py¶

To install pagure via this mechanism simply follow these steps: # Clone the sources:

git clone https://pagure.io/pagure.git

# Go to the folder:

cd pagure

# Install the latest version of pagure:

python setup.py build
sudo python setup.py install

NOTE:

# Install the additional files as follow:

Set-up pagure¶

This folder is used by project maintainers to upload the tarball of the releases of their project.

This folder must be accessible by the user under which the application is running (in our case: git).

mkdir -p /var/www/releases
chown git:git /var/www/releases

Pagure stores the sources of a project in a git repo, offers a place to store the project's documentation in another repo, stores a JSON dump of all issues and of all pull-requests in another two repos, and keeps a local checkout of remote projects when asked to do remote pull-requests. All these repositories are stored in different folders that must be created manually.

For example you can place them under /srv/git/repositories/ which would make /srv/git the home of your gitolite user.

You would then create the folders with:

mkdir /srv/git/repositories/{docs,forks,tickets,requests,remotes}

If installed by RPM, you will find an example apache configuration file at: /etc/httpd/conf.d/pagure.conf.

If not installed by RPM, the example file is present in the sources at: files/pagure.conf.

Adjust it for your needs.

If you installed by RPM, you will find example WSGI files at: /usr/share/pagure/pagure.wsgi for the core server and /usr/share/pagure/doc_pagure.wsgi for the doc server.

If you did not install by RPM, these files are present in the sources at: files/pagure.wsgi and files/doc_pagure.wsgi.

Adjust them for your needs

For the sake of this document, we assume that the web application runs under the git user, the same user as your gitolite user, but apache itself runs under the httpd (or apache2) user. So by default, apache will not be allowed to read git repositories created and managed by gitolite.

To give apache this permission (required to make git clone via http work), we use file access control lists (aka FACL):

setfacl -m user:apache:rx --default
setfacl -Rdm user:apache:rx /srv/git
setfacl -Rm user:apache:rx /srv/git

Where /srv/git is the home of your gitolite user (which will thus need to be adjusted for your configuration).

This is an important step which concerns the file /etc/pagure/pagure.cfg. If you have installed pagure by RPM, this file is already there, otherwise you can find an example one in the sources at: files/pagure.cfg.sample that you will have to copy to the right location.

Confer the Configuration section of this documentation for a full explanation of all the options of pagure.

You first need to create the database itself. For this, since pagure can work with: PostgreSQL, MySQL or MariaDB, we would like to invite you to consult the documentation of your database system for this operation.

Once you have specified in the configuration file the to url used to connect to the database, and create the database itself, you can now create the tables, the database scheme.

For changes to existing tables, we rely on Alembic. It uses revisions to perform the upgrades, but to know which upgrades are needed and which are already done, the current revision needs to be saved in the database. This will allow alembic to know and apply the new revision when running it.

In the alembic.ini file, one of the configuration key is most important: script_location which is the path to the versions folder containing all the alembic migration files. The sqlalchemy.url configuration key if missing will be replaced by the url filled in the configuration file of pagure.

To create the database tables, you need to run the script /usr/share/pagure/pagure_createdb.py and specify the configuration to use for pagure and for alembic.

For example:

python /usr/share/pagure/pagure_createdb.py -c /etc/pagure/pagure.cfg -i /etc/pagure/alembic.ini

This will tell /usr/share/pagure/pagure_createdb.py to use the database information specified in the file /etc/pagure/pagure.cfg and to stamp the database at the last alembic revision.

WARNING:

For changes to existing tables, we rely on Alembic. It uses revisions to perform the upgrades, but to know which upgrades are needed and which are already done, the current revision needs to be saved in the database. This will allow alembic to know apply the new revision when running it.

In the alembic.ini file, one of the configuration key is most important: script_location which is the path to the versions folder containing all the alembic migration files. The sqlalchemy.url configuration key if missing will be replaced by the url filled in the configuration file of pagure.

WARNING:

NOTE:

If you installed by RPM, then enable and start the worker services

systemctl enable --now pagure_worker.service pagure_gitolite_worker.service

Set up virus scanning¶

Then edit /etc/freshclam.conf, removing the Example line and run freshclam once to get an up to date database.

Copy /usr/share/doc/clamav-server/clamd.conf to /etc/clamd.conf and edit that too, again making sure to remove the Example line. Make sure to set LocalSocket to a file in a directory that exists, and set User to an existing system user.

Then start the clamd service and set VIRUS_SCAN_ATTACHMENTS = True in the Pagure configuration.

Configure your system¶

python-pymilter

NOTE:

NOTE:

This can be done in /etc/aliases, for example:

reply:      /dev/null

In postfix this is done via:

recipient_delimiter = +

In postfix this is done via:

non_smtpd_milters = unix:/var/run/pagure/paguresock
smtpd_milters = unix:/var/run/pagure/paguresock

The first file is the script of the milter itself.

The second file is a file specific for systemd and ensuring the temporary folders needed by the milter are re-created if needed at each boot.

The third file is the systemd service file.

systemctl enable pagure_milter
systemctl start pagure_milter

Configure your system¶

python-redis
python-trololio

NOTE:

The first file is the script of the SSE server itself.

The second file is the systemd service file.

systemctl enable redis
systemctl start redis
systemctl enable pagure_ev
systemctl start pagure_ev

Configure your system¶

python-redis
python-trololio

NOTE:

The first file is the script of the web-hook server itself.

The second file is the systemd service file.

systemctl enable redis
systemctl start redis
systemctl enable pagure_webhook
systemctl start pagure_webhook

Configure your system¶

python-jenkins
python-redis
python-trololio

NOTE:

The first file is the pagure-ci service itself, triggering the build on the CI service when there is a new pull-request or a change to an existing one.

The second file is the systemd service file.

PAGURE_CI_SERVICES = ['jenkins']

systemctl enable redis
systemctl start redis
systemctl enable pagure_ci
systemctl start pagure_ci

Configure your system¶

python-redis
python-trololio

NOTE:

The first file is the pagure-loadjson service itself, triggered by the git hook (shipped with pagure itself) and loading the JSON files into the database.

The second file is the systemd service file.

systemctl enable redis
systemctl start redis
systemctl enable pagure_loadjson
systemctl start pagure_loadjson

Configure your system¶

python-redis
python-trololio

NOTE:

The first file is the pagure-logcom service itself, triggered by the git hook (shipped with pagure itself) and logging the commits into the database.

The second file is the systemd service file.

systemctl enable redis
systemctl start redis
systemctl enable pagure_logcom
systemctl start pagure_logcom

API key expiration reminder¶

The cron job can be found in the sources in:

files/api_key_expire_mail.py

In the RPM it is installed in:

/usr/share/pagure/api_key_expire_mail.py

This cron job is meant to be run daily using a syntax similar to:

10 0 * * * root python /usr/share/pagure/api_key_expire_mail.py

which will make the script run at 00:10 every day.

Must options¶

SECRET_KEY¶

SALT_EMAIL¶

DB_URL¶

Examples values:

DB_URL = 'mysql://user:pass@host/db_name'
DB_URL = 'postgres://user:pass@host/db_name'
DB_URL = 'sqlite:////var/tmp/pagure_dev.sqlite'

Defaults to sqlite:////var/tmp/pagure_dev.sqlite

APP_URL¶

Defaults to: http://localhost.localdomain/

EMAIL_ERROR¶

GIT_URL_SSH¶

The URL should end with a slash /.

Defaults to: 'ssh://git@llocalhost.localdomain/'

NOTE:

GIT_URL_GIT¶

The URL should end with a slash /.

Defaults to: 'git://localhost.localdomain/'

BROKER_URL¶

Defaults to: 'redis://%s' % APP.config['REDIS_HOST']

NOTE:

Repo Directories¶

There are then another 3 folders: one for specifying the locations of the forks, one for the remote git repo used for the remotes pull-requests (ie: those coming from a project not hosted on this instance of pagure), and one for user-uploaded tarballs.

GIT_FOLDER¶

Note that gitolite config value GL_REPO_BASE (if using gitolite 3) or $REPO_BASE (if using gitolite 2) must have exactly the same value as GIT_FOLDER.

REMOTE_GIT_FOLDER¶

UPLOAD_FOLDER_PATH¶

ATTACHMENTS_FOLDER¶

UPLOAD_FOLDER_URL¶

Defaults to: /releases/, unsafe for production!

WARNING:

SESSION_COOKIE_SECURE¶

Defaults to: False for development, must be True in production with https.

SESSION_TYPE¶

This is useful when the Pagure server needs to be scaled up to multiple instances, which requires the flask session keys to be shared between those. Flask-session allows you to use Redis, Memcached, relational database or MongoDB for storing shared session keys.

FROM_EMAIL¶

Defaults to: pagure@localhost.localdomain

DOMAIN_EMAIL_NOTIFICATIONS¶

Defaults to: localhost.localdomain

VIRUS_SCAN_ATTACHMENTS¶

Defaults to: False

GIT_AUTH_BACKEND¶

Git auth backends can either be static (like gitolite), where a file is generated when something changed and then used on login, or dynamic, where the actual ACLs are checked in a git hook before being applied.

By default pagure provides the following backends:

Defaults to: gitolite3

NOTE:

NOTE:

Configure Pagure Auth¶

This authentication mechanism uses keyhelper.py and aclchecker.py to check the Pagure database for user registered SSH keys to do the authentication.

The integrated authentication mechanism has two modes of operation: one where it is configured as the AuthorizedKeysCommand for the SSH user (preferred) and one where it is configured to manage the authorized_keys file for the SSH user.

In the preferred mode, when you attempt to do an action with a remote Git repo over SSH (e.g. git clone ssh://git@localhost.localdomain/repository.git), the SSH server will ask Pagure to validate the SSH user key. This has the advantage of performance (no racey and slow file I/O) but has the disadvantage of requiring changes to the system's sshd_config file to use it.

To use this variant, set the following in pagure.cfg:

GIT_AUTH_BACKEND = "pagure"
HTTP_REPO_ACCESS_GITOLITE = None
SSH_KEYS_USERNAME_EXPECT = "git"
SSH_COMMAND_NON_REPOSPANNER = ([
    "/usr/bin/%(cmd)s",
    "/srv/git/repositories/%(reponame)s",
], {"GL_USER": "%(username)s"})

Setting the following in /etc/ssh/sshd_config is also required:

Match User git
    AuthorizedKeysCommand /usr/libexec/pagure/keyhelper.py "%u" "%h" "%t" "%f"
    AuthorizedKeysCommandUser git

If you do not have the ability to modify the sshd configuration to set up the pagure backend, then you need to use the pagure_authorized_keys alternative backend. This backend will write to the git user's authorized_keys file instead. This is slower than the preferred mode and also has the disadvantage of making it impossible to scale to multiple Pagure frontend instances on top of a shared Git storage without causing races and triggering inconsistencies. It also adds to the I/O contention on a heavily used system, but for most smaller setups with few users, the trade-off is not noticeable.

To use this variant, enable the pagure_authorized_keys_worker service and set the following to pagure.cfg:

SSH_FOLDER = "/srv/git/.ssh"
GIT_AUTH_BACKEND = "pagure_authorized_keys"
HTTP_REPO_ACCESS_GITOLITE = None
SSH_COMMAND_NON_REPOSPANNER = ([
    "/usr/bin/%(cmd)s",
    "/srv/git/repositories/%(reponame)s",
], {"GL_USER": "%(username)s"})

Configure Gitolite¶

Pagure supports both gitolite 2 and gitolite 3 and the code generating the gitolite configuration can be customized for easier integration with other systems (cf custom-gitolite).

Using Gitolite also requires setting the following in pagure.cfg:

HTTP_REPO_ACCESS_GITOLITE = "/usr/share/gitolite3/gitolite-shell"
SSH_COMMAND_NON_REPOSPANNER = (
    [
        "/usr/share/gitolite3/gitolite-shell",
        "%(username)s",
        "%(cmd)s",
        "%(reponame)s",
    ],
    {},
)

This ensures that the Gitolite environment is used for interacting with Git repositories. Further customizations are listed below.

gitolite 2 and 3¶

GITOLITE_HOME¶

GITOLITE_KEYDIR¶

Since pagure is the user interface, it is pagure that writes down the files in this directory, effectively setting up the users to be able to use gitolite.

GITOLITE_CONFIG¶

GITOLITE_CELERY_QUEUE¶

Pagure provides a pagure_gitolite_worker.service systemd service file pre-configured to handles these messages if this configuration key is set to gitolite_queue.

gitolite 2 only¶

GL_RC¶

GL_BINDIR¶

gitolite 3 only¶

GITOLITE_HAS_COMPILE_1¶

There are two ways to have it,

Installing the compile-1 command:

Defaults to: False

EventSource options¶

EVENTSOURCE_SOURCE¶

EVENTSOURCE_PORT¶

NOTE:

Web-hooks notifications¶

WEBHOOK¶

Defaults to: False.

NOTE:

Redis options¶

REDIS_HOST¶

Defaults to: 0.0.0.0.

REDIS_PORT¶

Defaults to: 6379.

REDIS_DB¶

Defaults to: 0.

Authentication options¶

ADMIN_GROUP¶

PAGURE_ADMIN_USERS¶

Celery Queue options¶

FAST_CELERY_QUEUE¶

This will be used for tasks such as creating a new project, forking or merging a pull-request.

Defaults to: None.

MEDIUM_CELERY_QUEUE¶

This will be used for tasks such as updating a file in a git repository.

Defaults to: None.

SLOW_CELERY_QUEUE¶

This will be used for tasks such as updating the ticket git repo based on the content posted in the user interface.

Defaults to: None.

Stomp Options¶

STOMP_NOTIFICATIONS¶

Defaults to: False.

STOMP_BROKERS¶

STOMP_HIERARCHY¶

STOMP_SSL¶

Defaults to: False.

STOMP_KEY_FILE¶

STOMP_CERT_FILE¶

STOMP_CREDS_PASSWORD¶

ALWAYS_STOMP_ON_COMMITS¶

Defaults to: False.

API token ACLs¶

ACLS¶

USER_ACLS¶

Use this configuration key in combination with ADMIN_API_ACLS to disable certain ACLs for users while allowing admins to generate keys with them.

ADMIN_API_ACLS¶

Defaults to: ['issue_comment', 'issue_create', 'issue_change_status', 'pull_request_flag', 'pull_request_comment', 'pull_request_merge', 'generate_acls_project', 'commit_flag', 'create_branch']

CROSS_PROJECT_ACLS¶

Defaults to: ['create_project', 'fork_project', 'modify_project']

Optional options¶

Theming¶

THEME¶

For more information about theming see the usage/theming

Default options:

Defaults to: default

Git repository templates¶

PROJECT_TEMPLATE_PATH¶

FORK_TEMPLATE_PATH¶

SSH_KEYS¶

See the SSH hostkeys/Fingerprints page on pagure.io.

Where <foo> and <bar> must be replaced by your values.

CSP_HEADERS¶

Source: https://en.wikipedia.org/wiki/Content_Security_Policy

Defaults to:

CSP_HEADERS = (
    "default-src 'self' https:; "
    "script-src 'self' 'nonce-{nonce}'; "
    "style-src 'self' 'nonce-{nonce}'"
)

Where {nonce} is dynamically set by pagure.

LOGGING_GIT_HOOKS¶

If un-specified (default), the logging configuration used by the git hooks will be the same as the one for the web application (i.e.: defined in LOGGING here below).

Defaults to: None.

LOGGING¶

The default value is:

LOGGING = {
     "version": 1,
     "disable_existing_loggers": False,
     "formatters": {
         "standard": {
             "format": "%(asctime)s [%(levelname)s] %(name)s: %(message)s"
         },
         "email_format": {"format": MSG_FORMAT},
     },
     "filters": {"myfilter": {"()": ContextInjector}},
     "handlers": {
         "console": {
             "formatter": "standard",
             "class": "logging.StreamHandler",
             "stream": "ext://sys.stdout",
         },
         "auth_handler": {
             "formatter": "standard",
             "class": "logging.StreamHandler",
             "stream": "ext://sys.stdout",
         },
         "email": {
             "level": "ERROR",
             "formatter": "email_format",
             "class": "logging.handlers.SMTPHandler",
             "mailhost": "localhost",
             "fromaddr": "pagure@localhost",
             "toaddrs": "root@localhost",
             "subject": "ERROR on pagure",
             "filters": ["myfilter"],
         },
     },
     # The root logger configuration; this is a catch-all configuration
     # that applies to all log messages not handled by a different logger
     "root": {"level": "INFO", "handlers": ["console"]},
     "loggers": {
         "pagure": {
             "handlers": ["console"],
             "level": "DEBUG",
             "propagate": True,
         },
         "pagure_auth": {
             "handlers": ["auth_handler"],
             "level": "DEBUG",
             "propagate": False,
         },
         "flask": {
             "handlers": ["console"],
             "level": "INFO",
             "propagate": False,
         },
         "sqlalchemy": {
             "handlers": ["console"],
             "level": "WARN",
             "propagate": False,
         },
         "binaryornot": {
             "handlers": ["console"],
             "level": "WARN",
             "propagate": True,
         },
         "MARKDOWN": {
             "handlers": ["console"],
             "level": "WARN",
             "propagate": True,
         },
         "PIL": {"handlers": ["console"], "level": "WARN", "propagate": True},
         "chardet": {
             "handlers": ["console"],
             "level": "WARN",
             "propagate": True,
         },
         "pagure.lib.encoding_utils": {
             "handlers": ["console"],
             "level": "WARN",
             "propagate": False,
         },
     },
 }

NOTE:

'handlers': ['console', 'email'],

NOTE:

"auth_handler": {
    "formatter": "standard",
    "class": "logging.handlers.TimedRotatingFileHandler",
    "filename": "/var/log/pagure/pagure_auth.log",
    "backupCount": 10,
    "when": "midnight",
    "utc": True,
},

ITEM_PER_PAGE¶

Defaults to: 50.

PR_TARGET_MATCHING_BRANCH¶

Defaults to: False.

SSH_ACCESS_GROUPS¶

Defaults to: []

SMTP configuration¶

SMTP_SERVER¶

Defaults to: localhost.

See also the SMTP_STARTTLS section.

SMTP_PORT¶

SMTP by default uses TCP port 25. The protocol for mail submission is the same, but uses port 587. SMTP connections secured by SSL, known as SMTPS, default to port 465 (nonstandard, but sometimes used for legacy reasons).

Defaults to: 25

SMTP_SSL¶

Defaults to: False

SMTP_STARTTLS¶

When enabling STARTTLS in conjunction with a local smtp server, you should replace localhost with a host name that is included in the server's certificate. If the server only relays messages originating from localhost, then you should also ensure that the above host name resolves to the same tcp address as localhost, for instance by adding an appropriate record to /etc/hosts.

Defaults to: False

SMTP_KEYFILE¶

Defaults to: None

SMTP_CERTFILE¶

Defaults to: None

SMTP_USERNAME¶

Note: Specify SMTP_USERNAME and SMTP_PASSWORD for using SMTP auth

Defaults to: None

SMTP_PASSWORD¶

Note: Specify SMTP_USERNAME and SMTP_PASSWORD for using SMTP auth

Defaults to: None

SHORT_LENGTH¶

Defaults to: 6.

BLACKLISTED_PROJECTS¶

Defaults to:

[
    'static', 'pv', 'releases', 'new', 'api', 'settings',
    'logout', 'login', 'users', 'groups', 'about'
]

CHECK_SESSION_IP¶

Defaults to: True.

PAGURE_AUTH¶

Defaults to: local.

OIDC Settings¶

OIDC_CLIENT_SECRETS¶

OIDC_ID_TOKEN_COOKIE_SECURE¶

Defaults to: True for production with https, can be set to False for convenient development.

OIDC_SCOPES¶

OIDC_PAGURE_EMAIL¶

OIDC_PAGURE_FULLNAME¶

OIDC_PAGURE_USERNAME¶

OIDC_PAGURE_SSH_KEY¶

OIDC_PAGURE_GROUPS¶

OIDC_PAGURE_USERNAME_FALLBACK¶

IP_ALLOWED_INTERNAL¶

Defaults to: ['127.0.0.1', 'localhost', '::1'].

MAX_CONTENT_LENGTH¶

Defaults to: 4 * 1024 * 1024 which corresponds to 4 megabytes.

ENABLE_TICKETS¶

Defaults to: True

ENABLE_TICKETS_NAMESPACE¶

Defaults to: []

ENABLE_DOCS¶

Defaults to: True

ENABLE_NEW_PROJECTS¶

Defaults to: True

ENABLE_UI_NEW_PROJECTS¶

Defaults to: True

ENABLE_DEL_PROJECTS¶

Defaults to: True

ENABLE_DEL_FORKS¶

Defaults to: ENABLE_DEL_PROJECTS

GIT_HOOK_DB_RO¶

Defaults to: False

EMAIL_SEND¶

Defaults to: False.

NOTE:

FEDMSG_NOTIFICATIONS¶

Defaults to: False.

FEDORA_MESSAGING_NOTIFICATIONS¶

Defaults to: False.

ALWAYS_FEDMSG_ON_COMMITS¶

Defaults to: True.

ALLOW_DELETE_BRANCH¶

Defaults to: True.

ALLOW_ADMIN_IGNORE_EXISTING_REPOS¶

Defaults to: False.

USERS_IGNORE_EXISTING_REPOS¶

Defaults to: [].

LOCAL_SSH_KEY¶

Defaults to True.

DEPLOY_KEY¶

Defaults to True.

OLD_VIEW_COMMIT_ENABLED¶

For pagure instances older than 1.3, who care about backward compatibility, we added an endpoint view_commit_old that brings URL backward compatibility for URLs using the complete git hash (the 40 characters). For URLs using a shorter hash, the URLs will remain broken.

This configuration key enables or disables this backward compatibility which is useful for pagure instances running since before 1.3 but is not for newer instances.

Defaults to: False.

DISABLE_REMOTE_PR¶

Defaults to: False.

PAGURE_CI_SERVICES¶

To enable this integration, follow the documentation on how to install pagure-ci and set this configuration key to ['jenkins'] (Jenkins being the only CI service supported at the moment).

Defaults to: None.

WARNING:

INSTANCE_NAME¶

Defaults to: Pagure

ADMIN_EMAIL¶

Defaults to: root@localhost.localdomain

USER_NAMESPACE¶

Defaults to: False

DOC_APP_URL¶

Defaults to: None

PRIVATE_PROJECTS¶

Defaults to: True

EXCLUDE_GROUP_INDEX¶

The use-case is the following: the Fedora project is deploying pagure has a front-end for the git repos of the packages in the distribution, that means about 17,000 git repositories in pagure. The project has a group of people that have access to all of these repositories, so when viewing the user's page of one member of that group, instead of seeing all the project that this user works on, you can see all the projects hosted in that pagure instance. Using this configuration key, pagure will hide all the projects that this user has access to via the specified groups and thus return only the groups of forks of that users.

Defaults to: []

TRIGGER_CI¶

This configuration key can be used to define all the sentences that can be used to trigger this pagure-ci run. The format is following: {"<sentence>": {"name": "<name of the CI>", "description": "<short description>"}}

Sentences which have None as value won't show up in the "Rerun CI" dropdown. Additionally, it's possible to add a requires_project_hook_attr key to the dict with data about a sentence. For example, having "requires_project_hook_attr": ("ci_hook", "active_pr", True) would make the "Rerun CI" dropdown have a button for this specific CI only if the project has ci_hook activated and its active_pr value is True.

In versions before 5.2, this was a list containing just the sentences.

Defaults to: {"pretty please pagure-ci rebuild": {"name": "Default CI", "description": "Rerun default CI"}}

NOTE:

FLAG_STATUSES_LABELS¶

FLAG_SUCCESS¶

Defaults to: success

FLAG_FAILURE¶

Defaults to: failure

FLAG_PENDING¶

Defaults to: pending

EXTERNAL_COMMITTER¶

This feature can give access to all the projects on the instance, all but some or just some.

Defaults to: {}

To give access to all the projects to a group named fedora-altarch use a such a structure:

EXTERNAL_COMMITTER = {
    'fedora-altarch': {}
}

To give access to all the projects but one (named rpms/test) to a group named provenpackager use a such a structure:

EXTERNAL_COMMITTER = {
    'fedora-altarch': {},
    'provenpackager': {
        'exclude': ['rpms/test']
    }
}

To give access to just some projects (named rpms/test and modules/test) to a group named testers use a such a structure:

EXTERNAL_COMMITTER = {
    'fedora-altarch': {},
    'provenpackager': {
        'exclude': ['rpms/test']
    },
    'testers': {
        'restrict': ['rpms/test', 'modules/test']
    }
}

REQUIRED_GROUPS¶

Defaults to: {}

Example configuration:

REQUIRED_GROUPS = {
    'rpms/kernel': ['packager', 'kernel-team'],
    'modules/*': ['module-packager', 'packager'],
    'rpms/*': ['packager'],
    '*': ['contributor'],
}

With this configuration (evaluated in the provided order):

GITOLITE_PRE_CONFIG¶

This can be used in combination with GITOLITE_POST_CONFIG to further customize gitolite's configuration file. It can also be used with EXTERNAL_COMMITTER to give commit access to git repos based on external information.

Defaults to: None

GITOLITE_POST_CONFIG¶

This can be used in combination with GITOLITE_PRE_CONFIG to further customize gitolite's configuration file. It can also be used with EXTERNAL_COMMITTER to give commit access to git repos based on external information.

Defaults to: None

GIT_GARBAGE_COLLECT¶

The garbage collection run by Pagure will respect git settings, so you can tweak gc.auto and gc.autoPackLimit to your liking and that will have immediate effect on the task that runs the garbage collection. These values can be configured system-wide in /etc/gitconfig. See https://git-scm.com/docs/git-gc#git-gc---auto for more details.

This is especially useful if repositories are stored on NFS (or similar network storage), where file metadata access is expensive - having unpacked objects in repositories requires a lot of metadata reads.

Note that the garbage collection is only run on repos that are not on repoSpanner.

Defaults to: False

CELERY_CONFIG¶

Defaults to: {}

CASE_SENSITIVE¶

Defaults to: False

PROJECT_NAME_REGEX¶

Defaults to: ^[a-zA-z0-9_][a-zA-Z0-9-_]*$

APPLICATION_ROOT¶

Defaults to: '/'

ALLOWED_PREFIX¶

Defaults to: []

ADMIN_SESSION_LIFETIME¶

Defaults to: timedelta(minutes=20)

where timedelta comes from the python datetime module

BLACKLISTED_GROUPS¶

Defaults to: ['forks', 'group']

ENABLE_GROUP_MNGT¶

Defaults to: True

ENABLE_USER_MNGT¶

Defaults to: True

SESSION_COOKIE_NAME¶

Defaults to: 'pagure'

SHOW_PROJECTS_INDEX¶

Defaults to: ['repos', 'myrepos', 'myforks']

EMAIL_ON_WATCHCOMMITS¶

Defaults to: True

ALLOW_HTTP_PULL_PUSH¶

Defaults to: True

ALLOW_HTTP_PUSH¶

Defaults to: False

HTTP_REPO_ACCESS_GITOLITE¶

Defaults to: /usr/share/gitolite3/gitolite-shell

MIRROR_SSHKEYS_FOLDER¶

Defaults to: /var/lib/pagure/sshkeys/

LOG_ALL_COMMITS¶

Defaults to: False

DISABLE_MIRROR_IN¶

Defaults to: False

SYNTAX_ALIAS_OVERRIDES¶

It should be a dictionary containing the file extensions as keys and the highlighting language/category to use as values.

Defaults to: {".spec": "specfile", ".patch": "diff"}

ALLOW_API_UPDATE_GIT_TAGS¶

Default to: True

RepoSpanner Options¶

Support for this integration has been included in Pagure version 5.0 and higher.

Here below are the different options one can/should use to integrate pagure with repoSpanner.

REPOBRIDGE_BINARY¶

Defaults to: /usr/libexec/repobridge.

REPOSPANNER_NEW_REPO¶

Defaults to: None.

REPOSPANNER_NEW_REPO_ADMIN_OVERRIDE¶

Defaults to: False

REPOSPANNER_NEW_FORK¶

Defaults to: True

REPOSPANNER_ADMIN_MIGRATION¶

Defaults to: False

REPOSPANNER_REGIONS¶

An example entry could look like:

REPOSPANNER_REGIONS = {
    'default': {'url': 'https://nodea.regiona.repospanner.local:8444',
                'repo_prefix': 'pagure/',
                'hook': None,
                'ca': '/etc/pki/repospanner/pki/ca.crt',
                'admin_cert': {'cert': '/etc/pki/repospanner/pki/admin.crt',
                               'key': '/etc/pki/repospanner/pki/admin.key'},
                'push_cert': {'cert': '/etc/pki/repospanner/pki/pagure.crt',
                              'key': '/etc/pki/repospanner/pki/pagure.key'}}
}

If this configuration key is not defined, pagure will consider that it is not set to be integrated with repoSpanner.

Defaults to: {}

SSH_KEYS_USERNAME_LOOKUP¶

SSH_KEYS_USERNAME_FORBIDDEN¶

SSH_KEYS_USERNAME_EXPECT¶

SSH_KEYS_OPTIONS¶

SSH_ADMIN_TOKEN¶

This is useful when the IP address of sshd service is not predictable (e.g. because of running in a distributed cloud environment) and so it's not possible to use the IP_ALLOWED_INTERNAL address list.

Defaults to: None

SSH_COMMAND_REPOSPANNER¶

SSH_COMMAND_NON_REPOSPANNER¶

MQTT Options¶

Here below are the different configuration options to make it so.

MQTT_NOTIFICATIONS¶

Defaults to: False

MQTT_HOST¶

Defaults to: None

MQTT_PORT¶

Defaults to: None

MQTT_USERNAME¶

Defaults to: None

MQTT_PASSWORD¶

Defaults to: None

MQTT_CA_CERTS¶

Defaults to: None

MQTT_CERTFILE¶

Defaults to: None

MQTT_KEYFILE¶

Defaults to: None

MQTT_CERT_REQS¶

Defaults to: ssl.CERT_REQUIRED (from python's ssl library)

MQTT_TLS_VERSION¶

Defaults to: ssl.PROTOCOL_TLSv1_2 (from python's ssl library)

MQTT_CIPHERS¶

Defaults to: None

MQTT_TOPIC_PREFIX¶

Defaults to: None

ALWAYS_MQTT_ON_COMMITS¶

Defaults to: False.

PAGURE_PLUGINS_CONFIG¶

Deprecated configuration keys¶

FORK_FOLDER¶

See the UPGRADING.rst file for more information about this change and how to handle it.

UPLOAD_FOLDER¶

GITOLITE_VERSION¶

Defaults to: 3.

This has been replaced by GITOLITE_BACKEND in the release 3.0 of pagure.

DOCS_FOLDER, REQUESTS_FOLDER, TICKETS_FOLDER¶

FILE_SIZE_HIGHLIGHT¶

Defaults to: 5000

BOOTSTRAP_URLS_CSS¶

Defaults to: 'https://apps.fedoraproject.org/global/fedora-bootstrap-1.1.1/fedora-bootstrap.css'

This has been deprecated by the new way of theming pagure, see the theming documentation

BOOTSTRAP_URLS_JS¶

Defaults to: 'https://apps.fedoraproject.org/global/fedora-bootstrap-1.1.1/fedora-bootstrap.js'

This has been deprecated by the new way of theming pagure, see the theming documentation

HTML_TITLE¶

Defaults to: Pagure

This has been deprecated by the new way of theming pagure, see the theming documentation

GITOLITE_BACKEND¶

PAGURE_PLUGIN¶

Loading the configuration¶

The configuration file¶

An example configuration can be seen in files/plugins.cfg.sample inside the Pagure repository.

Get the sources¶

git clone https://pagure.io/pagure.git

Contributors:

git clone ssh://git@pagure.io/pagure.git

Dependencies¶

sudo dnf install git python-virtualenv libgit2-devel \
                 libjpeg-devel gcc libffi-devel redhat-rpm-config

The python dependencies of pagure are listed in the file requirements.txt at the top level of the sources.

virtualenv pagure_env
source ./pagure_env/bin/activate
pip install pygit2==<version of libgit2 found>.* # e.g. 0.23.*
pip install -r requirements.txt

NOTE:

How to run pagure¶

Run pagure for development¶

Create the database scheme:

./createdb.py

Create the folder that will receive the different git repositories:

mkdir {repos,docs,forks,tickets,requests,remotes}

Run the server:

./runserver.py

If you want to change some configuration key you can create a file, place the configuration change in it and use it with

./runserver.py -c <config_file>

For example, create the file config with in it:

from datetime import timedelta
# Makes the admin session longer
ADMIN_SESSION_LIFETIME = timedelta(minutes=20000000)
# Use a postgresql database instead of sqlite
DB_URL = 'postgresql://user:pass@localhost/pagure'
# Change the OpenID endpoint
FAS_OPENID_ENDPOINT = 'https://id.stg.fedoraproject.org'
APP_URL = '*'
EVENTSOURCE_SOURCE = 'http://localhost:8080'
EVENTSOURCE_PORT = '8080'
DOC_APP_URL = '*'
# Avoid sending email when developing
EMAIL_SEND = False

and run the server with:

./runserver.py -c config

To get some profiling information you can also run it as:

./runserver.py --profile

You should be able to access the server at http://localhost:5000

Every time you save a file, the project will be automatically restarted so you can see your change immediately.

Create a pull-request for testing¶

Making a pull-request for development purposes isn't hard, if you remember that since you're running a local instance, the git repos created in your pagure instance are also local.

So here are in a few steps that one could perform to create a pull-request in a local pagure instance.

mkdir clones

cd clones
git clone ~/path/to/pagure/repos/test.git
cd test

echo "*~" > .gitignore
git add .gitignore
git commit -m "Add a .gitignore file"
echo "BSD" > LICENSE
git add LICENSE
git commit -m "Add a LICENSE file"

git push -u origin master

git branch new_branch
git checkout new_branch
touch test
git add test
git commit -m "Add file: test"

git push -u origin new_branch

Then go back to your pagure instance running in your web-browser, check the test project. You should see two branches: master and new_branch. From there you should be able to open a new pull-request, either from the front page or via the File Pull Request button in the Pull Requests page.

Coding standards¶

We run the source code through black as part of the tests, so you may have to do some adjustments or run it yourself (which is simple: black /path/to/pagure).

NOTE:

dnf install python3-flake8 python3-black

yum install python3-flake8 python3-black

Send patch¶

The workflow would therefore be something like:

git branch <my_shiny_feature>
git checkout <my_shiny_feature>
<work>
git commit file1 file2
<more work>
git commit file3 file4
git checkout master
git pull
git checkout <my_shiny_feature>
git rebase master
git format-patch -2

This will create two patch files that you can send by email to submit in a ticket on pagure, by email or after forking the project on pagure by submitting a pull-request (in which case the last step above git format-patch -2 is not needed.

NOTE:

Unit-tests¶

We aim at having a full (100%) coverage of the whole code (including the Flask application) and of course a smart coverage as in we want to check that the functions work the way we want but also that they fail when we expect it and the way we expect it.

Tests checking that function are failing when/how we want are as important as tests checking they work the way they are intended to.

So here are a few steps that one could perform to run unit-tests in a local pagure instance.

pip install -r requirements-testing.txt

tox ./test/

If you want to run a single interpreter, cou can use:

tox -e py38 ./test/

Each unit-tests files (located under tests/) can be called by alone, allowing easier debugging of the tests. For example:

pytest-3 tests/test_pagure_lib.py

NOTE:

dnf install python3-pytest-cov

To run the unit-tests, there is also a container available with all the dependencies needed. Use the following command to run the tests

$ ./dev/run-tests-container.py

This command will build a fedora based container and execute the test suite. You can also limit the tests to unit-test files or single tests similar to the options described above. You need set the environment variables REPO and BRANCH if the tests are not yet available in the upstream pagure master branch.

List of locations where Pagure is currently used¶

This documentation is generated from the doc folder in the pagure's sources. Feel free to report issues about the documentation on the pagure issue tracker or even better, contribute to it!