.\" Man page generated from reStructuredText. . . .nr rst2man-indent-level 0 . .de1 rstReportMargin \\$1 \\n[an-margin] level \\n[rst2man-indent-level] level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] - \\n[rst2man-indent0] \\n[rst2man-indent1] \\n[rst2man-indent2] .. .de1 INDENT .\" .rstReportMargin pre: . RS \\$1 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] . nr rst2man-indent-level +1 .\" .rstReportMargin post: .. .de UNINDENT . RE .\" indent \\n[an-margin] .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] .nr rst2man-indent-level -1 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. .TH "PAGURE" "1" "Feb 21, 2023" "5.11.3" "pagure" .SH NAME pagure \- Pagure Documentation .sp Pagure is a light\-weight git\-centered forge based on pygit2. .sp Features: .INDENT 0.0 .IP \(bu 2 \fBOpen\-sources\fP: Web\-interface for the git repositories .IP \(bu 2 \fBFlexibility\fP: Ability to create any project you want .IP \(bu 2 \fBOne place\fP: Keep your documentation and tickets in pagure .IP \(bu 2 \fBCollaboration\fP: Fork a project and make a pull\-request .IP \(bu 2 \fBIntegration\fP: Create pull\-request from a fork hosted somewhere else than in pagure .IP \(bu 2 \fBOpen data\fP: Sources, doc, ticket and pull\-requests meta\-data are available in the web interface but also in git repos which can thus be cloned and changed locally. .IP \(bu 2 \fBFreedom\fP: Pagure is fully Free and Open\-Source Software! .UNINDENT .sp Resources: .INDENT 0.0 .IP \(bu 2 \fI\%Home page\fP .IP \(bu 2 \fI\%Git repository\fP .IP \(bu 2 \fI\%Github mirror\fP .UNINDENT .sp Contents: .SH OVERVIEW .sp Pagure is split over multiple components, each having their purpose and all but two (the core web application and its workers) being optional. .sp These components are: .SS Contents .INDENT 0.0 .IP \(bu 2 \fI\%Overview\fP .INDENT 2.0 .IP \(bu 2 \fI\%Pagure core application\fP .IP \(bu 2 \fI\%Pagure workers\fP .IP \(bu 2 \fI\%Gitolite\fP .IP \(bu 2 \fI\%Pagure doc server\fP .IP \(bu 2 \fI\%Pagure milter\fP .IP \(bu 2 \fI\%Pagure EventSource Server\fP .IP \(bu 2 \fI\%Pagure web\-hook Server\fP .IP \(bu 2 \fI\%Pagure load JSON service\fP .IP \(bu 2 \fI\%Pagure log com service\fP .UNINDENT .UNINDENT .sp Before going into the overall picture, one should realize that most of the components listed above are optional. .sp Here is a diagram representing pagure without all the optional components: \fI\%\fP .sp And here is a diagram of all the components together: \fI\%\fP.SS Pagure core application .sp 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. .SS Pagure workers .sp Interacting with git repos can be a long process, it varies depending on the size of the repository itself but also based on hardware performances or simply the load on the system. To make pagure capable of handling more load, since pagure 3.0 the interactions with the git repositories from the web UI is performed by dedicated workers, allowing async processing of the different tasks. .sp The communication between the core application and its worker is based on \fI\%celery\fP and defaults to using \fI\%redis\fP but any of the queueing system supported by \fI\%celery\fP could be used instead. .SS Gitolite .sp Currently pagure uses \fI\%gitolite\fP to grant or deny \fI\%ssh\fP access to the git repositories, in other words to grant or deny read and/or write access to the git repositories. .sp Pagure supports cloning over both ssh and http, but writing can only be done via ssh, through gitolite. .SS Pagure doc server .sp While integrated into the main application at first, it has been split out for security concern, displaying information directly provided by the user without a clear/safe way of filtering for unsafe script or hacks is a security hole. For this reason we also strongly encourage anyone wanting to deploy their own instance of pagure with the doc server, to run this application on a completely different domain name (not just a sub\-domain) in order to reduce the cross\-site forgery risks. .sp Pagure can be run just fine without the doc server, all you need to do is to \fBnot\fP define the variable \fBDOC_APP_URL\fP in the configuration file. .SS Pagure milter .sp The milter is a script, receiving an email as input and performing an action with it. .sp 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. .sp 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. .SS Pagure EventSource Server .sp Eventsource or Server Sent Events are messages sent from a server to a browser. .sp 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. .sp 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. .SS Pagure web\-hook Server .sp Sends notifications to third party services using POST http requests. .sp This is the second notifications system in pagure with \fI\%fedmsg\fP\&. 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. .sp 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. .SS Pagure load JSON service .sp The load JSON service is an async service updating the database based on information pushed to the ticket or pull\-request git repositories. This allows updating the database with information pushed to the git repositories without keeping the connection open with the client. .SS Pagure log com service .sp The log com (for log commit) service is an async service updating the log table of the database on every pushed made to any repository allowing to build the data for the calendar heatmap graph displayed on every user\(aqs page. .SH USAGE .sp Using pagure should come fairly easily, especially to people already used to forges such as GitHub or GitLab. There are however some tips and tricks which can be useful to know and that this section of the doc covers. .sp One of the major difference with GitHub and GitLab is that for each project on pagure, four git repositories are made available: .INDENT 0.0 .IP \(bu 2 A git repository containing the source code, displayed in the main section of the pagure project. .IP \(bu 2 A git repository for the documentation .IP \(bu 2 A git repository for the issues and their metadata .IP \(bu 2 A git repository for the metadata for pull\-requests .UNINDENT .sp Issues and pull\-requests repositories contain the meta\-data (comments, notifications, assignee...) from the issues and pull\-request. They are are not public and only available to admins and committers of the project, since they may contain private information. .sp You can use these repositories for offline access to your tickets or pull\-requests (the \fI\%pag\-off\fP project for example relies on a local copy of the issue git repository). They are designed to allow you to have full access to all the data about your project. One of the original idea was also to allow syncing a project between multiple pagure instances by syncing these git repositories between the instances. .sp You can find the URLs to access or clone these git repositories on the overview page of the project. On the top right of the page, in the drop\-down menu entitled \fBClone\fP\&. Beware that if documentation, the issue tracker or the pull\-requests are disabled on the project, the corresponding URL will not be shown. .sp Contents: .SS First Steps on pagure .sp When coming to pagure for the first time there are a few things one should do or check to ensure all works as desired. .SS Login to pagure or create your account .sp Pagure has its own user account system. .sp For instances of pagure such as the one at \fI\%pagure.io\fP 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. .sp 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. .sp 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. .SS Upload your SSH key .sp Pagure uses gitolite to manage who has read/write access to which git repository via \fI\%ssh\fP\&. .sp An ssh key is composed of two parts: .INDENT 0.0 .IP \(bu 2 a private key, which you must keep to yourself and never share with anyone. .IP \(bu 2 a public key, which is public and therefore can be shared with anyone. .UNINDENT .sp If you have never generated a ssh key, you can do so by running: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ssh\-keygen .ft P .fi .UNINDENT .UNINDENT .sp or alternatively on GNOME using the application \fBseahorse\fP\&. .sp This will create two files in \fB~/.ssh/\fP (\fB~\fP is the symbol for your home folder). .sp These two files will be named (for example) \fBid_rsa\fP and \fBid_rsa.pub\fP\&. 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. .sp To upload your public key onto pagure: .sp 1. Login into pagure and click on the user icon on the top right corner, there, select \fBMy settings\fP\&. \fI\%\fP .sp 2. In the authentication section of your user settings copy the content of your \fBid_rsa.pub\fP file in the Public SSH key text box and save your ssh key settings. \fI\%\fP.sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Pagure supports multiple ssh keys per user. To add more than one ssh key to your user account just add your new ssh key in your authentication settings (one key per row), this way you will be able to push commits to your repository from a different computer. .UNINDENT .UNINDENT .SS Configure the default email address .sp If the pagure instance you use is using local user authentication, you can choose whichever email address you prefer to use during account creation. But in the case (like pagure.io) where the pagure instance relies on an external authentication service, the email address provided by this service may be different from the one you prefer. .sp 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. .sp 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. .sp 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. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 All email addresses will need to be confirmed to be activated, this is done via a link sent by email to the address. If you do not receive this link, don\(aqt forget to check your spam folder! .UNINDENT .UNINDENT .SS Forks .sp A fork in Pagure is a copy of a repository. When contributing to a project on Pagure, the first step is to fork it. This gives you a place to make changes to the project and, if you so wish, contribute back to the original project. If you\(aqre not already familiar with Git\(aqs distributed workflow, \fI\%the Pro Git book has an excellent introduction\fP\&. .sp You can see a list of projects you\(aqve forked on your home page. .SS Create a Fork on Pagure .sp To fork a project, simply navigate to the project on Pagure and click the fork button. You will then be redirected to your new fork. .SS Configure your Local Git Repository .sp Now that you have forked the project on Pagure, you\(aqre ready to configure a local copy of the repository so you can get to work. First, clone the repository. The URL for the repository is on the right\-hand side of the project overview page. For example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ git clone ssh://git@pagure.io/forks/jcline/pagure.git $ cd pagure .ft P .fi .UNINDENT .UNINDENT .sp After cloning your fork locally, it\(aqs a good idea to add the upstream repository as a \fI\%git remote\fP\&. For example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ git remote add \-f upstream ssh://git@pagure.io/pagure.git .ft P .fi .UNINDENT .UNINDENT .sp This lets you pull in changes that the upstream repository makes after you forked. Consult Git\(aqs documentation for more details. .SS Pushing Changes .sp After you \fI\%Configure your Local Git Repository\fP you\(aqre ready to make your changes and contribute them upstream. First, start a new branch: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ git checkout \-b my\-feature\-or\-bugfix .ft P .fi .UNINDENT .UNINDENT .sp It\(aqs a good idea to give the branch a descriptive name so you can find it later. Next, make your changes. Once you\(aqre satisfied, add the changes to Git\(aqs staging area and commit the changes: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ git add \-A # add all changes $ git commit \-s # prepare changes for upload .ft P .fi .UNINDENT .UNINDENT .sp Your text editor of choice will open and you can write your commit message. If you have not done so already \fI\%Upload your SSH key\fP now. Afterwards, you are ready to push your changes to your remote fork: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ git push \-u origin my\-feature\-or\-bugfix # upload changes .ft P .fi .UNINDENT .UNINDENT .sp In case you cloned the repo via HTTP, for example using a command like \fIgit clone https://...\fP, the push will fail. Pagure.io does not support pushing over HTTP. An easy workaround is to use: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ git push \-u origin my\-feature\-or\-bugfix ssh://git@pagure.io/forks/jcline/pagure.git .ft P .fi .UNINDENT .UNINDENT .sp You are now ready to \fI\%Open a Pull Request\fP\&. .SS Understanding Read Only Mode of projects .sp If a project is in Read Only Mode, the users of the project may not be able to modify the git repository of the project. Let\(aqs say you forked a project, then the forked project goes into a read only mode. You won\(aqt be able to modify the git repository of the forked project in that mode. After the read only mode is gone, you can begin to use the git repository again. Let\(aqs say you decide to add another user to your fork, this time the project will go in read only mode again but, you still will be able to use the git repository while the new user will have to wait for read only mode to get over. This is also true when you remove a user from your project. The removed user can still access the project\(aqs git repository, given that he had at least commit access, until the read only mode is over. .sp 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\(aqs why Pagure does it outside of HTTP Request\-Response Cycle. .sp 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. .SS Actions that put the project in read only mode .sp All the actions that needs gitolite to be compiled, will bring the project in read only mode. .INDENT 0.0 .IP \(bu 2 Creating/Forking a project. (only the fork will be in read only mode) .IP \(bu 2 Adding/Removing a user/group from a project. .UNINDENT .SS HTTP PUSH .sp When using git push over http against a pagure instance, there are two situations to distinguish. .SS Git push over http with API token .sp This is going to be the most supported approach. Any user can generate API tokens with the \fBcommit\fP ACL which reads in the UI as: \fICommit to a git repository via http(s)\fP\&. These API tokens can be specific to a project if generated in the settings page of the project, or generic to all projects if generated in the user\(aqs settings page. In either case, they will no work if the user does not have at commit access to the project. .sp Once the API token has been generate, the user needs to enter it with git prompts for a password (instead of their actual password). .sp For example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ git push username: pingou password: ABC123... .ft P .fi .UNINDENT .UNINDENT .SS Git push over http with Username & Password .sp This is only supported on pagure instance that are using the \fBlocal\fP authentication system (ie: where pagure manages the registration of the user accounts, email confirmation, etc). .sp 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. .SS Storing the password/token .sp If you interact with git regularly, typing you password or API token will quickly become tiring. Thanksfully, git has a built\-in mechanism named \fI\%git credential store\fP which can take care of this for you. .sp You can use two modes for the store, either \fBcache\fP or \fBstore\fP\&. \- \fIcache\fP will cache your credential in memory for 15 minutes (by default) \- \fIstore\fP will actually store your credentials in \fBplain text\fP on disk .sp You can set this using either: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ git config credential.helper store $ git config credential.helper cache .ft P .fi .UNINDENT .UNINDENT .sp The timeout of the cache can be configured using: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ git config credential.helper \(aqcache \-\-timeout=3600\(aq .ft P .fi .UNINDENT .UNINDENT .sp Where the timeout value is a number of seconds (so here the cache is extended to one hour). .sp Finally, if you wish to use this configuration on multiple project, you can add the \fB\-\-global\fP 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. .SS Pull Requests .sp Pagure uses the concept of pull requests to contribute changes from your fork of a project back to the upstream project. To contribute a change to a project you first open a pull request with original project. The project maintainer then merges the pull request if they are satisfied with the changes you have proposed. .SS Open a Pull Request .sp Before you can open a pull request, you need to complete the \fI\%First Steps on pagure\fP and \fI\%Create a Fork on Pagure\fP of the project you would like to contribute to. Once you have a fork and you have pushed a \fI\%git branch\fP containing one or more \fI\%commits\fP, you are ready to contribute to the project. .SS Pagure to Pagure pull request .sp You can create a pull request from a pagure project, using one of the following options .SS From the project overview .INDENT 0.0 .IP 1. 3 Go the the \fBoverview\fP tab of your fork. .IP 2. 3 Locate your feature branch (Right hand side), and press the button \fBNew PR\fP button. .IP 3. 3 Fill the Create a pull request form (Title and Description) and create your pull request. .UNINDENT .sp Notes: The \fBNew PR\fP button appears only if there are commits not available in the main branch. \fI\%\fP.SS From the commits history .INDENT 0.0 .IP 1. 3 Go to the \fBcommit\fP tab of your fork and select your feature branch. .IP 2. 3 Press the \fBcreate pull request\fP button (above the latest commits). .IP 3. 3 Fill the Create a pull request form (Title and Description) and create your pull request. .UNINDENT \fI\%\fP.SS From the pull requests list .INDENT 0.0 .IP 1. 3 Go to the main project\(aqs (not your fork) pull requests list and press the \fBFile Pull Request\fP button. .IP 2. 3 Select the feature branch containing your changes from the dropdown menu. .IP 3. 3 Fill the Create a pull request form (Title and Description) and create your pull request. .UNINDENT \fI\%\fP.SS Remote Git to Pagure pull request .sp You can create a pull request from another git hosting platform (e.g. GitHub, GitLab). This is a remote pull request. .SS From the pull requests list .INDENT 0.0 .IP 1. 3 Go to the main project\(aqs (not your fork) pull requests list and press the \fBFile Pull Request\fP button. .IP 2. 3 Select the \fBRemote pull\-request\fP option from the dropdown menu. .IP 3. 3 Fill the New remote pull\-request form (Title, Git repo address and Git branch) and create your remote pull request. .UNINDENT .sp Congratulations! It is now up to the project maintainer to accept your changes by merging them. .SS Updating Your Pull Request .sp It is likely that project maintainers will request changes to your proposed code by commenting on your pull request. Don\(aqt be discouraged! This is an opportunity to improve your contribution and for both reviewer and reviewee to become better programmers. .sp 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. .SS Rebasing .sp You may encounter a situation where you want to include changes from the master branch that were made after you created your pull request. You can do this by \fI\%rebasing\fP your pull request branch and pushing it to your remote fork. .SS Working with Pull Requests .sp It\(aqs quite common to work with a pull request locally, either to build on top of it or to test it. You can do this easily using \fBgit fetch\fP to download the pull request followed by \fBgit checkout\fP to work with it as you would any local branch. The syntax for \fBgit fetch\fP is: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C git fetch $REMOTE pull/$PR_NUMBER/head:$BRANCHNAME .ft P .fi .UNINDENT .UNINDENT .sp For example, if you have PR#1 which \(dqadds support for foo\(dq you might run: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C git fetch origin pull/1/head:add\-foo\-support .ft P .fi .UNINDENT .UNINDENT .sp Then you can work with the \fBadd\-foo\-support\fP normally: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C git checkout add\-foo\-support .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 You may use \fB/\fP characters in your branch name if you want to group your pull requests by the submitter name, bug number, etc. For example, you could name your local branch \fBuser/add\-foo\-support\fP\&. .UNINDENT .UNINDENT .sp 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 \fB\&.git/config\fP file, for example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C [remote \(dqorigin\(dq] url = ssh://git@pagure.io/pagure.git fetch = +refs/heads/*:refs/remotes/origin/* .ft P .fi .UNINDENT .UNINDENT .sp Now add this line: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C fetch = +refs/pull/*/head:refs/remotes/origin/pr/* .ft P .fi .UNINDENT .UNINDENT .sp to that section as \fBthe first fetch line\fP, like this: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C [remote \(dqorigin\(dq] url = ssh://git@pagure.io/pagure.git fetch = +refs/pull/*/head:refs/remotes/origin/pr/* fetch = +refs/heads/*:refs/remotes/origin/* .ft P .fi .UNINDENT .UNINDENT .sp Obviously, the remote URL should be matching the URL of your project (pagure project in this example). .sp Now you can fetch the all the pull requests: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ 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 .ft P .fi .UNINDENT .UNINDENT .sp To checkout a particular pull request: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ git checkout pr/25413 Branch pr/2541 set up to track remote branch pr/2541 from origin. Switched to a new branch \(aqpr/2541\(aq .ft P .fi .UNINDENT .UNINDENT .sp You will now be able to use this branch to work from or on this pull requests. .sp 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 \fB~/.bashrc\fP the following function: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C function pullpr { remote=\(dq${2:\-origin}\(dq git fetch $remote pull/$1/head:pr_$1 git checkout pr_$1 } .ft P .fi .UNINDENT .UNINDENT .sp Then after sourcing your \fB~/.bashrc\fP 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) .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ 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 \(aqpr_58\(aq .ft P .fi .UNINDENT .UNINDENT .SS Using Markdown in Pagure .sp Pagure uses \fI\%Markdown syntax highlighting\fP as the base for formatting comments in issues, pull requests, and in Markdown files in repositories. For basic formatting, Pagure follows common Markdown formatting, but it also has some unique syntax for more advanced formatting. This help page helps demonstrate how to use Markdown in Pagure. .sp Pagure relies on the \fI\%Markdown\fP python module to do the conversion. It has enabled a few extensions: .INDENT 0.0 .IP \(bu 2 \fI\%Definition Lists\fP .IP \(bu 2 \fI\%Fenced Code Blocks\fP .IP \(bu 2 \fI\%Tables\fP .IP \(bu 2 \fI\%Smart Strong\fP .IP \(bu 2 \fI\%Admonition\fP .IP \(bu 2 \fI\%CodeHilite\fP .IP \(bu 2 \fI\%Sane lists\fP .UNINDENT .sp README files can also rely on: .INDENT 0.0 .IP \(bu 2 \fI\%Abbreviations\fP .IP \(bu 2 \fI\%Footnotes\fP .IP \(bu 2 \fI\%Table of Contents\fP .UNINDENT .sp While comments use: .INDENT 0.0 .IP \(bu 2 \fI\%New Line to Break\fP .UNINDENT .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 Pagure does not support linking to remote images, if you want to link to an image on a ticket, you will have to upload it to pagure. .UNINDENT .UNINDENT .SS Styling .sp You can mark up text with bold, italics, or strikethrough. .INDENT 0.0 .IP \(bu 2 .INDENT 2.0 .TP \fBStyle\fP: Bold .INDENT 7.0 .IP \(bu 2 Syntax: \fI** **\fP or \fI__ __\fP .IP \(bu 2 Example: \fI**This is bold text**\fP .IP \(bu 2 Output: \fBThis is bold text\fP .UNINDENT .UNINDENT .IP \(bu 2 .INDENT 2.0 .TP \fBStyle\fP: Italics .INDENT 7.0 .IP \(bu 2 Syntax: \fI* *\fP or \fI_ _\fP .IP \(bu 2 Example: \fI_This is italicized text_\fP .IP \(bu 2 Output: \fIThis is italicized text\fP .UNINDENT .UNINDENT .IP \(bu 2 .INDENT 2.0 .TP \fBStyle\fP: Strikethrough .INDENT 7.0 .IP \(bu 2 Syntax: \fI~~ ~~\fP .IP \(bu 2 Example: \fI~~This text is no longer relevant~~\fP .IP \(bu 2 Output: This text is no longer relevant .UNINDENT .UNINDENT .IP \(bu 2 .INDENT 2.0 .TP \fBStyle\fP: Bold and italics .INDENT 7.0 .IP \(bu 2 Syntax: \fI** **\fP and \fI_ _\fP .IP \(bu 2 Example: \fI** This text is the _most important thing ever_ **\fP .IP \(bu 2 Output: ** This text is the \fImost important thing ever\fP ** .UNINDENT .UNINDENT .UNINDENT .SS Quoting .sp You can show text as being quoted with the \fI>\fP character. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C Before merging this pull request, remember Clark Kent mentioned this: > Double\-check there\(aqs no reference to the Kryptonite library in the program since we removed that a few versions ago. .ft P .fi .UNINDENT .UNINDENT .sp Before merging this pull request, remember Clark Kent mentioned this: .INDENT 0.0 .INDENT 3.5 Double\-check there\(aqs no reference to the Kryptonite library in the program since we removed that a few versions ago. .UNINDENT .UNINDENT .sp You can also make a line\-wrapping blockquote using
. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C Remember what Solomon said: > I don\(aqt want to survive.
I want to live. .ft P .fi .UNINDENT .UNINDENT .sp Remember what Solomon said: .INDENT 0.0 .INDENT 3.5 I don\(aqt want to survive. .sp I want to live. .UNINDENT .UNINDENT .sp For more details regarding Blockquote, refer \fI\%Blockquote\fP\&. .SS Code .sp You can highlight parts of a line as code or create entire code blocks in your Markdown documents. You can do this with the backtick character (\(ga). Text inside of backticks will not be formatted. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C When running the program for the first time, use \(gasuperman \-\-initialize\(ga. .ft P .fi .UNINDENT .UNINDENT .sp When running the program for the first time, use \fBsuperman \-\-initialize\fP\&. .sp To format multiple lines of code into its own block, you can wrap the text block with four tilde (~) characters .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C Install the needed system libraries: \(ga~~~~\(ga sudo dnf install git python\-virtualenv libgit2\-devel \e libjpeg\-devel gcc libffi\-devel redhat\-rpm\-config \(ga~~~~\(ga .ft P .fi .UNINDENT .UNINDENT .sp Install the needed system libraries: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C sudo dnf install git python\-virtualenv libgit2\-devel \e libjpeg\-devel gcc libffi\-devel redhat\-rpm\-config .ft P .fi .UNINDENT .UNINDENT .SS Hyperlinks .SS Regular links .sp Need to embed a link to somewhere else? No problem! You can create an in\-line link by wrapping the text in \fI[ ]\fP and appending the URL in parentheses \fI( )\fP immediately after. .sp \fIPagure is used by the [Fedora Project](https://fedoraproject.org).\fP .sp Pagure is used by the \fI\%Fedora Project\fP\&. .SS Links to ticket/PR of the same project .sp You want to link to a ticket or a pull\-request in the current project? Easy just use \fI#\fP immediately followed by the identifier of the ticket or pull\-request. .sp \fIThis is an example for #2921\fP .sp This is an example for \fI\%#2921\fP .SS Links to ticket/PR of another project .sp You want to link to a ticket or a pull\-request of a different project? Simply add the project name in front of the \fI#\fP and immediately followed by the identifier of the ticket or pull\-request. .sp \fIThis is an example for pagure#2921\fP .sp This is an example for \fI\%pagure#2921\fP .SS Lists .SS Unordered lists .sp You can make unordered lists spanning multiple lines with either \fI\-\fP or \fI*\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C * Superman * Batman * Protector of Gotham City! * Superwoman * Harley Quinn * Something on this list is unlike the others... .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .IP \(bu 2 Superman .IP \(bu 2 .INDENT 2.0 .TP .B Batman .INDENT 7.0 .IP \(bu 2 Protector of Gotham City! .UNINDENT .UNINDENT .IP \(bu 2 Superwoman .IP \(bu 2 .INDENT 2.0 .TP .B Harley Quinn .INDENT 7.0 .IP \(bu 2 Something on this list is unlike the others... .UNINDENT .UNINDENT .UNINDENT .SS Ordered lists .sp You can make ordered lists by preceding each line with a number. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C 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! .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .IP 1. 3 Superman .IP 2. 3 .INDENT 3.0 .TP .B Batman .INDENT 7.0 .IP 1. 3 Protector of Gotham City! .IP 2. 3 He drives the Batmobile! .UNINDENT .UNINDENT .IP 3. 3 Superwoman .IP 4. 3 .INDENT 3.0 .TP .B Harley Quinn .INDENT 7.0 .IP 1. 3 Something on this list is unlike the others... .IP 2. 3 Somebody evil lurks on this list! .UNINDENT .UNINDENT .UNINDENT .SS Tagging users .sp You can tag other users on Pagure to send them a notification about an issue or pull request. To tag a user, use the \fI@\fP symbol followed by their username. Typing the \fI@\fP symbol in a comment will bring up a list of users that match the username. The list searches as you type. Once you see the name of the person you are looking for, you can click their name to automatically complete the tag. .sp \fI@jflory7, could you please review this pull request and leave feedback?\fP .sp \fI\%@jflory7\fP, could you please review this pull request and leave feedback? .SS Tagging issues or pull requests .sp In a comment, you can automatically link a pull request or issue by its number. To link it, use the \fI#\fP character followed by its number. Like with tagging users, Pagure will provide suggestions for issues or pull requests as you type the number. You can select the issue in the drop\-down to automatically tag the issue or pull request. .sp 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 \fI#id\fP or \fI/#id\fP\&. .SS Emoji .sp Pagure natively supports emoji characters. To use emoji, you can use two colons wrapped around the emoji keyword (\fI:emoji:\fP). Typing a colon by itself will bring up a list of suggested emoji with a small preview. If you see the one you are looking for, you can click it to automatically complete the emoji. .sp \fII reviewed the PR and it looks good to me. :+1: Good to merge! :clapper:\fP .sp I reviewed the PR and it looks good to me. 👍 Good to merge! 🎬 .SS Improve this documentation! .sp Notice anything that can be improved in this documentation? Find a mistake? You can improve this page! Find it in the official \fI\%Pagure repository\fP\&. .SS Project settings .sp Each project have a number of options that can be tweaked in the settings page of the project which is accessible to the person having full commits to the project. .sp This page presents the different settings and there effect. .SS \fIAlways merge\fP .sp This Boolean enables or disables always making a merge commit when merging a pull\-request. .sp When merging a pull\-request in pagure there are three states: .INDENT 0.0 .IP \(bu 2 fast\-forward: when the commits in the pull\-request can be fast\-forwarded pagure signals it and just fast\-forward the commit, keeping the history linear. .IP \(bu 2 merge: when the commits in the pull\-request cannot be merged without a merge commit, pagure signals it and performs this merge commit. .IP \(bu 2 conflicts: when the commits in the pull\-request cannot be merged at all automatically due to one or more conflicts. Then pagure signals it and prevent merging. .UNINDENT .sp If the \fIAlways merge\fP option is on, then the \fIfast\-forward\fP option above is disabled in favor of the \fImerge\fP option. .SS \fIComment editing\fP .sp This Boolean enables or disables editing comments. .sp 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. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 notification about a comment is only sent once with the original text, changes performed later will not trigger a new notification. .UNINDENT .UNINDENT .sp Some project may not want to allow editing comments after they were posted and this setting allows turning it on or off. .SS \fIEnforce signed\-off commits in pull\-request\fP .sp This Boolean enables or disables checking for a \(aqSigned\-off\-by\(aq line (case insensitive) in the commit messages of the pull\-requests. .sp If this line is missing, pagure will display a message near the \fIMerge\fP button, allowing project admin to request the PR to be updated. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 This setting does not prevent commits without this \(aqsigned\-off\-by\(aq line to be pushed directly, it only work at the pull\-request level. .UNINDENT .UNINDENT .SS \fIIssue tracker\fP .sp This Boolean simply enables or disables the issue tracker for the project. So if you are tracking your ticket on a different system, you can simply disable reporting issue on pagure by un\-checking this option. .SS \fIMinimum score to merge pull\-request\fP .sp This option can be used for project wishing to enforce having a minimum number of people reviewing a pull\-request before it can be merged. .sp 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. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Only the main comments (i.e.: not in\-line) are taken into account to calculate the score of the pull\-request. .UNINDENT .UNINDENT .sp To vote in favor of a pull\-request, use either: * \fB+1\fP * \fB:thumbsup:\fP .sp To vote against a pull\-request, use either: * \fB\-1\fP * \fB:thumbsdown:\fP .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Pull\-Request not reaching the minimum score are not automatically merged .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Anyone can vote on the pull\-request, not only the contributors. .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Only one vote per person is taken into account to compute the final score. .UNINDENT .UNINDENT .SS \fIOnly assignee can merge pull\-request\fP .sp This option can be used for project wishing to institute a strong review workflow where pull\-request are first assigned then merged. .sp If this option is enabled, only the person assigned to the pull\-request can merge it. .SS \fIProject documentation\fP .sp Pagure offers the option to have a git repository specific for the documentation of the project. .sp This repository is then accessible under the \fBDocs\fP tab in the menu of the project. .sp If you prefer to store your documentation elsewhere or maybe even within the sources of the project, you can disable the \fBDocs\fP tab by un\-checking this option. .SS \fIPull requests\fP .sp Pagure offers the option to fork a project, make changes to it and then ask the developer to merge these changes into the project. This is similar to the pull\-request mechanism on GitHub or GitLab. .sp 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. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 disabling pull\-requests does \fInot\fP disable forking the projects. .UNINDENT .UNINDENT .SS \fIWeb\-hooks\fP .sp Pagure offers the option of sending notification about event happening on a project via [web\-hooks|https://en.wikipedia.org/wiki/Webhook]. This option is off by default and can be turned on for a pagure instance in its configuration file. .sp The URL of the web\-hooks can be entered in this field. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 See the \fBnotifications\fP documentation to learn more about web\-hooks in pagure and how to use them. .UNINDENT .UNINDENT .SS \fITags\fP .sp Pagure allows you to define \(dqtags\(dq that can be added to Issues. Tags are unique to each project, and they can only be defined in the project settings page. The Tag color can also be customized for a more robust visual representation of the tag. .SS \fIDeploy keys\fP .sp Deploy keys are SSH keys that have access to pull/push only to a single project. Upon creation, admins can determine whether this particular key has read/write access or read\-only. .SS Project Level Access Control .sp Till release 2.12, pagure had a very simple user model. If we added a new user or a new group to a project, the user/group would be an admin of the project. The user/group could do everything from changing the status of an issue to adding or removing any user on the project. With project ACL feature, we allow a more fine grained control over what a new user/group has access to, what things it can add or what actions it can take. .sp With Project ACL feature, We can now have three levels of access: .INDENT 0.0 .IP \(bu 2 Ticket: A user or a group with this level of access can only edit metadata of an issue. This includes changing the status of an issue, adding/removing tags from them, adding/removing assignees and every other option which can be accessed when you click \(dqEdit Metadata\(dq button in an issue page. However, this user can not \(dqcreate\(dq a new tag or \(dqdelete\(dq an existing tag because, that would involve access to settings page of the project which this user won\(aqt have. It also won\(aqt be able to \(dqdelete\(dq the issue because, it falls outside of \(dqEdit Metadata\(dq. .IP \(bu 2 Commit: A user or a group with this level of access can do everything what a user/group with ticket access can do + it can do everything on the project which doesn\(aqt include access to settings page. It can \(dqEdit Metadata\(dq of an issue just like a user with ticket access would do, can merge a pull request, can push to the main repository directly, delete an issue, cancel a pull request etc. .IP \(bu 2 Admin: The user/group with this access has access to everything on the project. All the \(dqusers\(dq of the project that have been added till now are having this access. They can change the settings of the project, add/remove users/groups on the project. .UNINDENT .SS Add/Update Access .INDENT 0.0 .IP \(bu 2 Every time you add a new user or a new group to the project, you will be asked to provide the level of access you want to give to that user or group. It\(aqs a required field in the form. .IP \(bu 2 To add a user or a group to a project, go to settings page of the project. There are buttons with text: \fIAdd User\fP and \fIAdd Group\fP\&. It will take you to a different page where you will have to select the user or group (depending on whether you clicked Add User or Add Group) and the access you want the user/group to have. .IP \(bu 2 If you want to update a user or a group\(aqs access, go to settings page of the project. There is a section which lists users associated with the project with the buttons to edit their access and a different button to remove them from the project. If you click the edit button, you will be taken to a different page where you can change the access and then click on Update button. .UNINDENT .SS Points to be noted .INDENT 0.0 .IP \(bu 2 The creator of a project in pagure holds a more unique position than a normal user with admin access. The creator can not be removed by an admin. His access level can not be changed. But, an admin\(aqs access can be updated by a fellow admin or the creator himself. .IP \(bu 2 All the members of a group will have same access over the project except for the case mentioned in the next point. .IP \(bu 2 In cases when, a user is added to a project with an access level of \(dqA\(dq and a group is also added to the same project with access level \(dqB\(dq and that user is also present in the group then, the user will enjoy the access of higher of \(dqA\(dq and \(dqB\(dq. Meaning, if the user earlier had access of ticket and the group had access of commit, the user will enjoy the access of a committer. And, if the user earlier had access of commit and the group had access of ticket, the user will still be a committer. .UNINDENT .SS Using the roadmap feature .sp Pagure allows building the roadmap of the project using the tickets and their milestones. .sp The principal is as follow: .INDENT 0.0 .IP \(bu 2 For each milestones defined in the settings of the project, the roadmap will group tickets with the corresponding milestone. .IP \(bu 2 If your project has an \fBunplanned\fP milestone, this milestone will be shown at the bottom of the roadmap page. This allowing you to put something on the roadmap without assigning a real milestone to it. .UNINDENT .SS Example .sp For a project named \fBtest\fP on \fBpagure.io\fP\&. .INDENT 0.0 .IP \(bu 2 First, go to the settings page of the project, create the milestones you like, for example: \fBv1.0\fP and \fBv2.0\fP\&. .IP \(bu 2 For the tickets you want to be on these milestones, go through each of them and set their milestone to either \fBv1.0\fP or \fBv2.0\fP, or none of them if the ticket is not on the roadmap. You can set the milestone on the metadata panel on the right side of the issue page. .IP \(bu 2 And this is how it will look like .UNINDENT \fI\%\fP.SS Flags .sp 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. .sp This feedback can be as simple as the outcome of running the tests, or some lint tool, or test coverage evolution. .SS Add a flag .sp Flags can be set via the API, see the \fB/api/\fP URL in your pagure instance or at \fI\%pagure.io/api/\fP and look for the endpoints with the titles: \fBFlag a commit\fP or \fBFlag a pull\-request\fP\&. .INDENT 0.0 .IP \(bu 2 \fBuid\fP: the API endpoints to add flag have an optional UID argument. It is a unique identifier (of maximum 32 characters) that is unique the commit or pull\-request that is being/has been flagged. If it is not specified by the user/tool adding the flag, it will be automatically generated and in either case, will be returned in the JSON data returned by the API endpoints. Note that this is the only time you would be able to retrieve this identifier if you do not specify it yourself. .IP \(bu 2 \fBstatus\fP: this field indicates the status of the task in the system running it. Pagure supports the following statuses: .INDENT 2.0 .IP \(bu 2 \fBsuccess\fP: the task ended successfully. .IP \(bu 2 \fBcanceled\fP: the task was canceled. .IP \(bu 2 \fBfailure\fP: the task ended but failed. .IP \(bu 2 \fBerror\fP: the task did not end at all. .IP \(bu 2 \fBpending\fP: the results of this task are pending. (for \fBfailure\fP vs \fBerror\fP think of the test system ran the tests but they failed vs the test system did not get to run the tests) .UNINDENT .IP \(bu 2 \fBpercent\fP: this is an optional field which can be used to provide some more details about the outcome of the task. For example this could be used for test coverage, or the number of test that failed/passed. .IP \(bu 2 \fBusername\fP: the name of the system running the tests. While not being restricted in length, a shorter name will render better in the interface. .IP \(bu 2 \fBcomment\fP: a free text form not restricted in length (however, here as well if the comment is too long it may render off in the interface). .IP \(bu 2 \fBurl\fP: the URL the flag is linked to and where the user should be able to retrieve more information about the task and its outcome. .UNINDENT .SS Example of two flags on a commit: \fI\%\fP.SS Example of two flags on a pull\-request: \fI\%\fP.SS Magic Words .sp Magic words are words and constructs you can use in your commit message to make pagure act on tickets or pull\-requests. .SS Enabling magic words .sp These magic words are enabled if the \fBpagure\fP git hook is enable. To do so, go to your project\(aqs \fBsettings\fP page, open the \fBHooks\fP tab and activate there the \fBPagure\fP hook. .SS Using magic words .sp To reference an issue/PR you need to use one of recognized keywords followed by a reference to the issue or PR, separated by whitespace and and optional colon. Such references can be either: .INDENT 0.0 .IP \(bu 2 The issue/PR number preceded by the # symbol .IP \(bu 2 The full URL of the issue or PR .UNINDENT .sp If using the full URL, it is possible to reference issues in other projects. .sp The recognized keywords are: .INDENT 0.0 .IP \(bu 2 fix/fixed/fixes .IP \(bu 2 relate/related/relates .IP \(bu 2 merge/merges/merged .IP \(bu 2 close/closes/closed .IP \(bu 2 resolve/resolves/resolved .UNINDENT .sp Examples: .INDENT 0.0 .IP \(bu 2 Fixes #21 .IP \(bu 2 related: \fI\%https://pagure.io/myproject/issue/32\fP .IP \(bu 2 this commit merges #74 .IP \(bu 2 Merged: \fI\%https://pagure.io/myproject/pull\-request/74\fP .UNINDENT .sp Capitalization does not matter; neither does the colon (\fB:\fP) between keyword and number. .SS Using the doc repository of your project .sp In this section of the documentation, we are interested in the doc repository. .sp 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: .INDENT 0.0 .IP \(bu 2 inline under the \fIDocs\fP tab in Pagure: .INDENT 2.0 .IP \(bu 2 \fI\%https://pagure.io/docs\fP// or .IP \(bu 2 \fI\%https://pagure.io/docs\fP/// .UNINDENT .IP \(bu 2 standalone: .INDENT 2.0 .IP \(bu 2 \fI\%https://docs.pagure.org\fP// or .IP \(bu 2 \fI\%https://docs.pagure.org\fP/./ .UNINDENT .UNINDENT .sp By default the \fIDocs\fP tab in the project\(aqs menu is disabled, you will have to visit the project\(aqs settings page and turn it on in the \fBProject options\fP section. .sp The URL to clone the doc repo is: .INDENT 0.0 .IP \(bu 2 \fI\%https://pagure.io/docs\fP//.git .UNINDENT .sp To view the doc source files in the browser: .INDENT 0.0 .IP \(bu 2 if the doc repo is kept in the project\(aqs sources, use the project\(aqs website .IP \(bu 2 if the doc repo is a dedicated repo, use \fI\%https://pagure.io\fP// .UNINDENT .sp Different file types can be used for your documentation in this repo: .INDENT 0.0 .IP \(bu 2 simple text files .sp Pagure will display them as plain text. If one of these is named \fBindex\fP it will be presented as the front page. .IP \(bu 2 RST or markdown files .sp Pagure will convert them to HTML on the fly and display them as such. The RST files must end with \fB\&.rst\fP and the markdown ones must end with \fB\&.mk\fP, \fB\&.md\fP or simply \fB\&.markdown\fP\&. .IP \(bu 2 HTML files .sp Pagure will simply show them as such. .UNINDENT .sp Updating documentation hosted in a dedicated repo is like \fI\%using other repos\fP\&. .SS Example .sp Pagure\(aqs documentation is kept in pagure\(aqs sources, in the \fIdoc\fP folder there. You can see it at: \fI\%https://pagure.io/pagure/blob/master/f/doc\fP\&. This doc can be built with \fI\%Sphinx\fP to make it HTML and prettier. .sp The built documentation is available at: \fI\%https://docs.pagure.org/pagure/\fP\&. .sp This is how it is built/updated: .INDENT 0.0 .IP \(bu 2 Clone pagure\(aqs sources: .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C git clone https://pagure.io/pagure.git .ft P .fi .UNINDENT .UNINDENT .IP \(bu 2 Move into its doc folder: .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C cd pagure/doc .ft P .fi .UNINDENT .UNINDENT .IP \(bu 2 Build the doc: .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C make html .ft P .fi .UNINDENT .UNINDENT .IP \(bu 2 Clone pagure\(aqs doc repository: .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C git clone ssh://git@pagure.io/docs/pagure.git .ft P .fi .UNINDENT .UNINDENT .IP \(bu 2 Copy the result of sphinx\(aqs build to the doc repo: .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C cp \-r _build/html/* pagure/ .ft P .fi .UNINDENT .UNINDENT .IP \(bu 2 Go into the doc repo and update it: .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C cd pagure git add . git commit \-am \(dqUpdate documentation\(dq git push .ft P .fi .UNINDENT .UNINDENT .IP \(bu 2 Clean the sources: .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C cd .. rm \-rf pagure # remove the doc repo rm \-rf _build # remove the output from the sphinx\(aqs build .ft P .fi .UNINDENT .UNINDENT .UNINDENT .sp To make things simpler, the following script (name \fIupdate_doc.sh\fP) can be used: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C #!/bin/bash make html git clone \(dqssh://git@pagure.io/docs/$1.git\(dq cp \-r _build/html/* $1/ ( cd $1 git add . git commit \-av git push ) rm \-rfI _build rm \-rfI $1 .ft P .fi .UNINDENT .UNINDENT .sp It can be used by running \fIupdate_doc.sh \fP from within the folder containing the doc. .sp So for pagure it would be something like: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C cd pagure/doc update_doc.sh pagure .ft P .fi .UNINDENT .UNINDENT .SS Using web\-hooks .sp Web\-hooks are a notification system that could be compared to a callback. Basically, pagure will make a HTTP POST request to one or more third party server/application with information about what is or just happened. .SS Activating web\-hooks notifications .sp To set\-up a web\-hook, simply go to the settings page of your project and enter the URL to the server/endpoint that will receive the notifications. If you wish to enter multiple URLs, enter one per line. To stop all notifications, clear out that field. .sp 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... .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The notifications sent via web\-hooks have the same payload as the notifications sent via \fI\%fedmsg\fP\&. Therefore, the list of pagure topics as well as example messages can be found in the \fI\%fedmsg documentation about pagure\fP .UNINDENT .UNINDENT .SS Authenticating the notifications .sp There is, in the settings page, a web\-hook key which is used by the server (here pagure) to sign the message sent and which you can use to ensure the notifications received are coming from the right source. .sp Each POST request made contains some specific headers: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C X\-Pagure X\-Pagure\-Project X\-Pagure\-Signature X\-Pagure\-Signature\-256 X\-Pagure\-Topic .ft P .fi .UNINDENT .UNINDENT .sp \fBX\-Pagure\fP contains URL of the pagure instance sending this notification. .sp \fBX\-Pagure\-Project\fP contains the name of the project on that pagure instance. .sp \fBX\-Pagure\-Signature\fP contains the signature of the message allowing to check that the message comes from pagure. .sp \fBX\-Pagure\-Signature\-256\fP contains the SHA\-256 signature of the message allowing to check that the message comes from pagure. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 These headers are present to allow you to verify that the webhook was actually sent by the correct Pagure instance. These are not included in the signed data. .UNINDENT .UNINDENT .sp \fBX\-Pagure\-Topic\fP is a global header giving a clue about the type of action that just occurred. For example \fBissue.edit\fP\&. .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 The headers \fBX\-Pagure\fP, \fBX\-Pagure\-Project\fP and \fBX\-Pagure\-Topic\fP are present for convenience only, they are not signed and therefore should not be trusted. Rely on the payload after checking the signature to make any decision. .UNINDENT .UNINDENT .sp Pagure relies on \fBhmac\fP to sign the content of its messages. If you want to validate the message, in python, you can do something like the following: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C 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(\(aqX\-Pagure\-Signature\(aq): raise Exception(\(aqMessage received with an invalid signature\(aq) .ft P .fi .UNINDENT .UNINDENT .SS Templates for ticket input .sp Pagure offers the possibility to add templates for ticket\(aqs input. These templates do not enforce anything, users will have the possibility to simply ignore it, or even to not follow it, but it also helps structuring the ticket opened against a project and highlighting the information that are often requested/needed. .sp The templates are provided in the git repository containing the meta\-data for the tickets. They must be placed under a \fBtemplates\fP folder in this git repository, end with \fB\&.md\fP and as the extension suggests can be formatted as markdown. .sp If you create a template \fBtemplates/default.md\fP, it will be shown by default when someone ask to create a new ticket. .SS Example .sp For a project named \fBtest\fP on \fBpagure.io\fP\&. .INDENT 0.0 .IP \(bu 2 First, clone the ticket git repo [1] and move into it .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C git clone ssh://git@pagure.io/tickets/test.git cd test .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .IP \(bu 2 Create the templates folder .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C mkdir templates .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .IP \(bu 2 Create a default template .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C vim templates/default.md .ft P .fi .UNINDENT .UNINDENT .sp And place in this file the following content: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ##### Issue ##### Steps to reproduce 1. 2. 3. ##### Actual results ##### Expected results .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .IP \(bu 2 Commit and push the changes to the git repo .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C git add templates git commit \-m \(dqAdd a default template for tickets\(dq git push .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .IP \(bu 2 And this is how it will look like .UNINDENT \fI\%\fP .IP [1] 5 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 \fBSource GIT URLs\fP\&. Click on \fBmore\fP to see them if you are logged in and have access to the repository (the ticket and request git repositories require a \fIcommit\fP access or higher). .SS Customize the PR page .sp Pagure offers the possibility to customize the page that creates pull\-request to add your specific information, such as: please follow the XYZ coding style, run the tests or whatever you wish to inform contributors when they open a new pull\-request. .sp 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 \fBtemplates\fP folder, be named \fBcontributing.md\fP and can be formatted as you wish using markdown. .SS Example .sp For a project named \fBtest\fP on \fBpagure.io\fP\&. .INDENT 0.0 .IP \(bu 2 First, clone the pull\-request git repo [1] and move into it .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C git clone ssh://git@pagure.io/requests/test.git cd test .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .IP \(bu 2 Create the templates folder .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C mkdir templates .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .IP \(bu 2 Create the customized PR info .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C vim templates/contributing.md .ft P .fi .UNINDENT .UNINDENT .sp And place in this file the following content: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C 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 \(ga\(garuntests.py\(ga\(ga 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 \(ga\(gapython\-pep8\(ga\(ga and run the \(ga\(gapep8\(ga\(ga CLI tool .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .IP \(bu 2 Commit and push the changes to the git repo .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C git add templates git commit \-m \(dqCustomize the PR page\(dq git push .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .IP \(bu 2 And this is how it will look like .UNINDENT \fI\%\fP .IP [1] 5 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 \fBSource GIT URLs\fP, click on \fBmore\fP to see them. .SS Theming Guide .sp Pagure is built on Flask, and uses Jinja2 for templates. Pagure also includes the ability to apply different themes that control the look and feel of your pagure instance, or add or remove elements from the interface. .SS Setting a theme .sp The theme is set in the Pagure configuration file. The theme name is defined by the name of the directory in the /themes/ folder that contains the theme. For example to enable the theme that is used on Pagure.io, add the following line to your Pagure configuration: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C THEME = \(dqpagureio\(dq .ft P .fi .UNINDENT .UNINDENT .SS Theme contents .sp A theme requires two directories (\fItemplates\fP and \fIstatic\fP) in the directory that contains the theme. The only other required file is theme.html which is placed in the templates directory .SS templates/ .sp The \fItemplates\fP directory is where pagure will look for the \fItheme.html\fP template. Additionally, if you wish to override any template in Pagure, place it in the theme templates/ directory, and pagure will use that template rather than the standard one. .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 Take care when overriding templates, as any changes to Pagure upstream will need to be backported to your theme template override. .UNINDENT .UNINDENT .SS static/ .sp The \fIstatic\fP directory contains all the static elements for the theme, including additional a favicon, images, Javascript, and CSS files. To reference a file in the theme static directory use the jinja2 tag \fI{{ url_for(\(aqtheme.static\(aq, filename=\(aqfilename\(aq)}}\fP\&. For example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C .ft P .fi .UNINDENT .UNINDENT .SS templates/theme.html .sp The theme.html file defines a subset of items in the Pagure interface that are commonly changed when creating a new theme. Theming is a new feature in Pagure, so this set is currently small, but please file issues or PRs against pagure with ideas of new items to include. .sp The current items configurable in theme.html are: .SS \fImasthead_class\fP variable .sp A string of additional CSS class(es) to be added to the navbar element. This navbar element is the topbar in Pagure. For example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {% set masthead_class = \(dqnavbar\-dark bg\-dark\(dq %} .ft P .fi .UNINDENT .UNINDENT .SS \fImasthead_navbar_items()\fP macro .sp A Jinja macro that allows themes to inject custom items in the Pagure navigation bar. Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {% macro masthead_navbar_items() %}
  • Foobar
    • {% endmacro %} .ft P .fi .UNINDENT .UNINDENT .SS \fIsite_title\fP variable .sp A string containing the text to append at the end of the html title on every page on the site. Usage: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {% set site_title = \(dqPagure\(dq %} .ft P .fi .UNINDENT .UNINDENT .SS \fIprojectstring(Bool:plural)\fP macro .sp A macro that returns a string used to refer to Projects in Pagure The plural parameter informs if the string to be returned is the plural form. This macro is optional. Usage: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {% macro projectstring(plural=False) \-%} {% if plural %} Repositories {% else %} Repository {% endif %} {% endmacro \-%} .ft P .fi .UNINDENT .UNINDENT .SS \fIprojecticon\fP variable .sp A string containing the name of the fontawesome icon to use for Projects. This variable is optional. Usage: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {% set projecticon = \(dqPackage\(dq %} .ft P .fi .UNINDENT .UNINDENT .SS \fIhead_imports()\fP macro .sp A Jinja macro that defines the additional items in the html head to be imported. The base templates do not include the bootstrap CSS, so this needs to be included in this macro in your theme. Additionally, include your favicon here, and a link to any additional CSS files your theme uses. Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {% macro head_imports() %} {% endmacro %} .ft P .fi .UNINDENT .UNINDENT .SS \fIjs_imports()\fP macro .sp A Jinja macro that defines the additional javascript files to be imported. The base templates do not include the bootstrap JS, so this needs to be included in this macro in your theme. Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {% macro js_imports() %} {% endmacro %} .ft P .fi .UNINDENT .UNINDENT .SS \fIbrowseheader_message(select)\fP macro .sp An optional Jinja macro that defines the welcome message that is shown above the tabs on the Browse Pages (Projects, Users, and Groups). The select parameter is a string with the name of the page being shown Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {% macro browseheader_message(select) %} {% if select == \(aqprojects\(aq %}

    Welcome to my Pagure

    Pagure is an Open Source software code hosting system.

    {% endif %} {% endmacro %} .ft P .fi .UNINDENT .UNINDENT .SS \fIfooter()\fP macro .sp A Jinja macro that defines the footer of the Pagure site. Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {% macro footer() %}

    Powered by Pagure {{ g.version }}

    SSH Hostkey/Fingerprint | Documentation

    {% endmacro %} .ft P .fi .UNINDENT .UNINDENT .SS \fIabout_page()\fP macro .sp A Jinja macro that defines the content of the About page (available at /about). You may want to replace the links to contact links for your own instance. Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {% macro about_page() %}

    About

    This is an instance of Pagure, a git forge.

    If you experience a bug or security concern, please submit an issue.

    You may also post questions to the Pagure Development list by emailing: pagure\-devel@lists.pagure.io or subscribe to the list.

    Subscribe to announcements about Pagure.

    {% endmacro %} .ft P .fi .UNINDENT .UNINDENT .SS Upgrade a database .sp For changes to the database schema, we rely on \fI\%Alembic\fP\&. This allows us to do upgrade and downgrade of schema migration, kind of like one would do commits in a system like git. .sp To upgrade the database to the latest version simply run: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C alembic upgrade head .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 if pagure\(aqs configuration file isn\(aqt in \fB/etc/pagure/pagure.cfg\fP you will have to specify it to alembic using the command: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C PAGURE_CONFIG=/path/to/pagure.cfg alembic upgrade head .ft P .fi .UNINDENT .UNINDENT .sp This allow applies for the command specified below. .UNINDENT .UNINDENT .sp This may fail for different reasons: .INDENT 0.0 .IP \(bu 2 The change was already made in the database .UNINDENT .sp This can be because the version of the database schema saved is incorrect. It can be debugged using the following commands: .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 Find the current revision: .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C alembic current .ft P .fi .UNINDENT .UNINDENT .IP \(bu 2 See the entire history: .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C alembic history .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp 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: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C alembic stamp .ft P .fi .UNINDENT .UNINDENT .sp 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 \fBalembic upgrade\fP until it works. .INDENT 0.0 .IP \(bu 2 The database used does not support some of the changes .UNINDENT .sp 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. .sp In some cases, if you are using a SQLite database, you will have to destroy it and create a new one. .SS Pagure CI .sp Pagure CI is a service integrating the results of Continuous Integration (CI) services, such as jenkins or travis\-ci, into pull\-requests opened against your project on pagure. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 By default pagure\-ci is off, an admin of your pagure instance will need to configure it to support one or more CI services. Check the configuration section on how to do that. .UNINDENT .UNINDENT .sp Contents: .SS Jenkins with Pagure\-ci .sp Jenkins is a Continuous Integration service that can be configured to be integrated with pagure. .sp This document describe the steps needed to make it work. .SS How does it work? .sp The principal is: .INDENT 0.0 .IP \(bu 2 pagure will trigger a build on jenkins when a pull\-request is created, updated or when someone explicitly asks pagure to do so or when a new commit is pushed (if pagure\-ci is configured to trigger on commit). .IP \(bu 2 pagure will send a few information to jenkins when triggering a build: \fBREPO\fP, \fBBRANCH\fP, \fBBRANCH_TO\fP, \fBcause\fP\&. .IP \(bu 2 jenkins will do its work and, using webhook, report to pagure that it has finished its task .IP \(bu 2 pagure will query jenkins to know the outcome of the task and flag the PR accordingly .UNINDENT .sp \fBREPO\fP corresponds to the url of the repository the pull\-request originates from (so most often it will be a fork of the main repository). .sp \fBBRANCH\fP corresponds to the branch the pull\-request originates from (the branch of the fork). .sp \fBBRANCH_TO\fP corresponds to the targeted branch in the main repository (the branch of the main project in which the PR is to be merged). .sp \fBcause\fP is the reason the build was triggered (ie: the pull\-request id or the commit hash). .SS How to enable Pagure CI .INDENT 0.0 .IP \(bu 2 Visit the settings page of your project .IP \(bu 2 Scroll down to the \fIHooks\fP section and click on \fIPagure CI\fP .IP \(bu 2 Select the type of CI service you want .IP \(bu 2 Enter the URL of the CI service. For example \fIhttp://jenkins.fedoraproject.org\fP .IP \(bu 2 Enter the name of the job the CI service will trigger. For example \fIpagure\-ci\fP .IP \(bu 2 Tick the checkbox activating the hook. Either trigger on every commits, trigger only on pull\-requests or both every commits and pull\-requests. .UNINDENT .sp 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. .SS Configure Jenkins .sp These steps can only be made by the admins of your jenkins instance, but they only need to be made once. .INDENT 0.0 .IP \(bu 2 Download the following plugins: .INDENT 2.0 .IP \(bu 2 \fI\%Git Plugin\fP .IP \(bu 2 \fI\%Notification Plugin\fP .UNINDENT .UNINDENT .SS Configure your project on Jenkins .INDENT 0.0 .IP \(bu 2 Go to the \fIConfigure\fP page of your project .IP \(bu 2 Under \fIJob Notification\fP click \fIAdd Endpoint\fP .IP \(bu 2 Fields in Endpoint will be : .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C FORMAT: JSON PROTOCOL: HTTP EVENT: All Events URL: TIMEOUT: 3000 LOG: 1 .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .IP \(bu 2 Tick the checkbox \fIThis build is parameterized\fP .IP \(bu 2 Add two \fIString Parameters\fP named REPO and BRANCH .IP \(bu 2 Source Code Management select Git and give the URL of the pagure project .IP \(bu 2 Under Build Trigger click on Trigger build remotely and specify the token given by pagure. .IP \(bu 2 Under Build \-> Add build step \-> Execute Shell .IP \(bu 2 In the box given enter the shell steps you want for testing your project. .UNINDENT .sp Example Script .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # Script specific for Pull\-Request build if [ \-n \(dq$REPO\(dq \-a \-n \(dq$BRANCH\(dq ]; then git remote rm proposed || true git remote add proposed \(dq$REPO\(dq git fetch proposed git checkout origin/master git config \-\-global user.email \(dqyou@example.com\(dq git config \-\-global user.name \(dqYour Name\(dq git merge \-\-no\-ff \(dqproposed/$BRANCH\(dq \-m \(dqMerge PR\(dq fi # Part of the script specific to how you run the tests on your project .ft P .fi .UNINDENT .UNINDENT .SS Tips and tricks .INDENT 0.0 .IP \(bu 2 How to re\-trigger a run of pagure\-ci on a pull\-request? .UNINDENT .sp To manually trigger a run of pagure\-ci on a given pull\-request, simply add a comment saying: \fBpretty please pagure\-ci rebuild\fP\&. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 To always have this handy, you can save it in the \fBQuick Replies\fP! .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 This trigger can also be configured per pagure instance via the configuration file. .UNINDENT .UNINDENT .SS Quick replies .sp Quick replies are reusable pieces of text that you can use to start a comment on an issue or pull request. They are meant to remove the hassle of typing a similar response again and again. .sp Examples where this can be handy: .INDENT 0.0 .IP \(bu 2 asking for a rebase of a pull request .IP \(bu 2 asking a person to add a \fBSigned\-off\-by\fP line to their commit .UNINDENT .sp All these requests might be accompanied by a description on why it\(aqs requested. With quick replies you can prepare the descriptions and the just use them with a click of a button. .SS Using quick replies .sp Any user that can comment will be able to use the quick reply. They are offered in a drop down menu next to the \fIPreview\fP button above comment form. [image] .sp The button is only visible if the project has some quick replies defined. .sp 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. .SS Creating and modifying quick replies .sp Project admins can create them in the settings section. There are no length limits on the reply, but only the first 50 characters will be displayed in the menu for users to choose from. This limitation should encourage you to put the most important message at the beginning. .sp 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. .SS Troubleshooting .sp This page lists some of the potential issues one may have in pagure as well as their solution(s). .sp Contents: .SS Inaccessible pull\-requests .SS The symptoms .sp When trying to open a pull\-request, if you run into this error: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C The branch into which this pull\-request was to be merged: XXX seems to no longer be present in this repo .ft P .fi .UNINDENT .UNINDENT .sp (Where \fBXXX\fP is a branch name). \fI\%\fP .sp (Here \fBXXX\fP is \fBm2\fP). .sp 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. .sp The pull\-request is thus inaccessible but remains in the list of open pull\-requests. .SS The solution .sp The easiest solution to solve this problem is to re\-create the target branch in your repo. .sp This can be done using git simply by doing: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C git checkout \-b git push origin .ft P .fi .UNINDENT .UNINDENT .sp It will create the branch named \fB\fP 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. .SS Tips and tricks .sp This page contains some tips and tricks on how to use pagure. These do not fit in their own page but are worth mentioning. .SS Place image onto your overview page .sp You can only use images that come from the Pagure host itself. .SS Example .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ![See Copr workflow](/copr/copr/raw/master/f/doc/img/copr\-workflow.png) .ft P .fi .UNINDENT .UNINDENT .sp Text in the square brackets will be used as an alt description. .SS Pre\-fill issue using the URL .sp When creating issues for a project pagure supports pre\-filling the title and description input text using URL parameters. .SS Example: .sp \fI\%https://pagure.io/pagure/new_issue/\fP?title=&content= .sp The above URL will autofill the text boxes for Title and Description field with Title set to and Description set to . .SS Pre\-fill issue template using the URL .sp When creating issues for a project pagure supports pre\-filling the title and description input text using URL parameters. .SS Example: .sp \fI\%https://pagure.io/pagure/new_issue/\fP?template= .sp 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 \fBtemplates\fP directory of the ticket git repository). .SS Filter for issues \fInot\fP having a certain tag .sp Very much in the same way pagure allows you to filter for issues having a certain tag, pagure allows one to filter for issues \fInot\fP having a certain tag. To do this, simply prepend a \fB!\fP in front of the tag. .SS Example: .sp \fI\%https://pagure.io/pagure/issues?tags=!easyfix\fP .SS Local user creation without email verification .sp If you set \fBEMAIL_SEND\fP to \fB\(gaFalse\(ga\fP from the configuration file, you will get the emails printed to the console instead of being sent. The admin of the instance can then access the URL to manually validate the account from there. This is generally used for development where we don\(aqt need to send any emails. .SS Filter an user\(aqs projects by their access .sp When watching a user\(aqs page, the list of all the project that user is involved in is presented regardless of whether the user has ticket, commit, admin access or is the main admin of the project. .sp You can specify an \fBacl=\fP argument to the URL to filter the list of projects by access. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 This also works for your home page when you are logged in. .UNINDENT .UNINDENT .SS Examples: .sp \fI\%https://pagure.io/user/pingou?acl=main\fP admin \fI\%https://pagure.io/user/pingou?acl=admin\fP \fI\%https://pagure.io/user/pingou?acl=commit\fP .SS Filter issues by (custom) fields .sp Via the project\(aqs settings page, admins can set custom keys to be used in issues. You can search them using the URL via the arguments \fBckeys\fP and \fBcvalue\fP or simpler, using the search field at the top of the issue page. .sp This also works for the following regular fields: \fBtags\fP, \fBmilestones\fP, \fBauthor\fP, \fBassignee\fP, \fBstatus\fP, \fBpriority\fP (but tags and milestones despite their name only support a single value). .SS Examples: .sp \fI\%https://pagure.io/SSSD/sssd/issues?status=Open&search_pattern=review%3ATrue\fP \fI\%https://pagure.io/pagure/issues?status=Open&search_pattern=tags%3Aeasyfix\fP .SS Search the comments of issues .sp One can search all the comments made on an issue tracker using \fBcontent:\fP in the search field. This is going to search all the comments (including the descriptions) of all the tickets and thus can be quite slow on large project. This is why this feature isn\(aqt being pushed much forward. .SS Examples: .sp \fI\%https://pagure.io/pagure/issues?status=Open&search_pattern=content%3Aeasyfix\fP .SS Pagure API .sp The API documentation can be found at \fI\%https://pagure.io/api/0/\fP or in \fB/api/0/\fP of you local pagure instance. .SH INSTALLING PAGURE .sp There are two ways to install pagure: .INDENT 0.0 .IP \(bu 2 via the RPM package (recommended if you are using a RPM\-based GNU/Linux distribution) .IP \(bu 2 via the setup.py .UNINDENT .SS Installing pagure via RPM .sp Here as well there are two ways of obtaining the RPM: .INDENT 0.0 .IP \(bu 2 From the main repositories .UNINDENT .sp Pagure is packaged for Fedora since Fedora 21 and is available for RHEL and its derivative via the \fIEPEL repository \fP\&. So installing it is as easy as: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C dnf install pagure pagure\-milters pagure\-ev pagure\-webhook .ft P .fi .UNINDENT .UNINDENT .sp or .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C yum install pagure pagure\-milters pagure\-ev pagure\-webhook .ft P .fi .UNINDENT .UNINDENT .sp The \fBpagure\fP package contains the core of the application and the doc server. (See the \fBOverview\fP page for a global overview of the structure of the project). .sp The \fBpagure\-milters\fP package contains, as the name says, the milter (a mail filter to hook into a MTA). .sp The \fBpagure\-ev\fP package contains the eventsource server. .sp The \fBpagure\-webhook\fP package contains the web\-hook server. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The last three packages are optional, pagure would work fine without them but the live\-update, the webhook and the comment by email services will not work. .UNINDENT .UNINDENT .INDENT 0.0 .IP \(bu 2 From the sources .UNINDENT .sp If you wish to run a newer version of pagure than what is in the repositories you can easily rebuild it as RPM. .sp Simply follow these steps: # Clone the sources: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C git clone https://pagure.io/pagure.git .ft P .fi .UNINDENT .UNINDENT .sp # Go to the folder: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C cd pagure .ft P .fi .UNINDENT .UNINDENT .sp # Build a tarball of the latest version of pagure: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C python setup.py sdist .ft P .fi .UNINDENT .UNINDENT .sp # Build the RPM: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C rpmbuild \-ta dist/pagure*.tar.gz .ft P .fi .UNINDENT .UNINDENT .sp This will build pagure from the version present in your clone. .sp Once, the RPM is installed the services \fBpagure_milter\fP and \fBpagure_ev\fP are ready to be used but the database and the web\-application parts still need to be configured. .SS Installing pagure via setup.py .sp Pagure includes in its sources a \fBsetup.py\fP automating the installation of the web applications of pagure (ie: the core + the doc server). .sp To install pagure via this mechanism simply follow these steps: # Clone the sources: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C git clone https://pagure.io/pagure.git .ft P .fi .UNINDENT .UNINDENT .sp # Go to the folder: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C cd pagure .ft P .fi .UNINDENT .UNINDENT .sp # Install the latest version of pagure: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C python setup.py build sudo python setup.py install .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 To install the eventsource server or the milter, refer to their respective documentations. .UNINDENT .UNINDENT .sp # Install the additional files as follow: .TS center; |l|l|. _ T{ Source | Destination T} _ T{ \fBfiles/pagure.cfg.sample\fP | \fB/etc/pagure/pagure.cfg\fP T} _ T{ \fBfiles/alembic.ini\fP T} T{ \fB/etc/pagure/alembic.ini\fP T} _ T{ \fBfiles/pagure.conf\fP T} T{ \fB/etc/httpd/conf.d/pagure.conf\fP T} _ T{ \fBfiles/pagure.wsgi\fP T} T{ \fB/usr/share/pagure/pagure.wsgi\fP T} _ T{ \fBcreatedb.py\fP T} T{ \fB/usr/share/pagure/pagure_createdb.py\fP T} _ .TE .SS Set\-up pagure .sp Once pagure\(aqs files are installed, you still need to set up some things. .INDENT 0.0 .IP \(bu 2 Create the folder release .UNINDENT .sp This folder is used by project maintainers to upload the tarball of the releases of their project. .sp This folder must be accessible by the user under which the application is running (in our case: \fBgit\fP). .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C mkdir \-p /var/www/releases chown git:git /var/www/releases .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .IP \(bu 2 Create the folders where the repos, forks and checkouts will be stored .UNINDENT .sp Pagure stores the sources of a project in a git repo, offers a place to store the project\(aqs 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. .sp For example you can place them under \fB/srv/git/repositories/\fP which would make \fB/srv/git\fP the home of your gitolite user. .sp You would then create the folders with: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C mkdir /srv/git/repositories/{docs,forks,tickets,requests,remotes} .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .IP \(bu 2 Configure apache .UNINDENT .sp If installed by RPM, you will find an example apache configuration file at: \fB/etc/httpd/conf.d/pagure.conf\fP\&. .sp If not installed by RPM, the example file is present in the sources at: \fBfiles/pagure.conf\fP\&. .sp Adjust it for your needs. .INDENT 0.0 .IP \(bu 2 Configure the WSGI file .UNINDENT .sp If you installed by RPM, you will find example WSGI files at: \fB/usr/share/pagure/pagure.wsgi\fP for the core server and \fB/usr/share/pagure/doc_pagure.wsgi\fP for the doc server. .sp If you did not install by RPM, these files are present in the sources at: \fBfiles/pagure.wsgi\fP and \fBfiles/doc_pagure.wsgi\fP\&. .sp Adjust them for your needs .INDENT 0.0 .IP \(bu 2 Give apache permission to read the repositories owned by the \fBgit\fP user. .UNINDENT .sp For the sake of this document, we assume that the web application runs under the \fBgit\fP user, the same user as your gitolite user, but apache itself runs under the \fBhttpd\fP (or \fBapache2\fP) user. So by default, apache will not be allowed to read git repositories created and managed by gitolite. .sp To give apache this permission (required to make git clone via http work), we use file access control lists (aka FACL): .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C setfacl \-m user:apache:rx \-\-default setfacl \-Rdm user:apache:rx /srv/git setfacl \-Rm user:apache:rx /srv/git .ft P .fi .UNINDENT .UNINDENT .sp Where \fB/srv/git\fP is the home of your gitolite user (which will thus need to be adjusted for your configuration). .INDENT 0.0 .IP \(bu 2 Set up the configuration file of pagure .UNINDENT .sp This is an important step which concerns the file \fB/etc/pagure/pagure.cfg\fP\&. If you have installed pagure by RPM, this file is already there, otherwise you can find an example one in the sources at: \fBfiles/pagure.cfg.sample\fP that you will have to copy to the right location. .sp Confer the \fBConfiguration\fP section of this documentation for a full explanation of all the options of pagure. .INDENT 0.0 .IP \(bu 2 Create the database .UNINDENT .sp You first need to create the database itself. For this, since pagure can work with: \fI\%PostgreSQL\fP, \fI\%MySQL\fP or \fI\%MariaDB\fP, we would like to invite you to consult the documentation of your database system for this operation. .sp 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. .sp For changes to existing tables, we rely on \fI\%Alembic\fP\&. It uses \fIrevisions\fP 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. .sp In the \fBalembic.ini\fP file, one of the configuration key is most important: \fBscript_location\fP which is the path to the \fBversions\fP folder containing all the alembic migration files. The \fBsqlalchemy.url\fP configuration key if missing will be replaced by the url filled in the configuration file of pagure. .sp To create the database tables, you need to run the script \fB/usr/share/pagure/pagure_createdb.py\fP and specify the configuration to use for pagure and for alembic. .sp For example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C python /usr/share/pagure/pagure_createdb.py \-c /etc/pagure/pagure.cfg \-i /etc/pagure/alembic.ini .ft P .fi .UNINDENT .UNINDENT .sp This will tell \fB/usr/share/pagure/pagure_createdb.py\fP to use the database information specified in the file \fB/etc/pagure/pagure.cfg\fP and to stamp the database at the last alembic revision. .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 Pagure\(aqs default configuration is using sqlite. This is fine for development purpose but not for production use as sqlite does not support all the operations needed when updating the database schema. Do use PostgreSQL, MySQL or MariaDB in production. .UNINDENT .UNINDENT .sp For changes to existing tables, we rely on \fI\%Alembic\fP\&. It uses \fIrevisions\fP 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. .sp In the \fBalembic.ini\fP file, one of the configuration key is most important: \fBscript_location\fP which is the path to the \fBversions\fP folder containing all the alembic migration files. The \fBsqlalchemy.url\fP configuration key if missing will be replaced by the url filled in the configuration file of pagure. .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 Calling \fBpagure_createdb.py\fP is asked regularly in the UPGRADING.rst documentation, especially to handle database schema changes upon upgrades, but the \fB\-\-initial\fP argument should only be used the first time as it will otherwise break upgrading the database schema via alembic. .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 When install from source the script is called \fBcreatedb.py\fP and not \fBpagure_createdb.py\fP\&. .UNINDENT .UNINDENT .sp If you installed by RPM, then enable and start the worker services .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C systemctl enable \-\-now pagure_worker.service pagure_gitolite_worker.service .ft P .fi .UNINDENT .UNINDENT .SS Set up virus scanning .sp Pagure can automatically scan uploaded attachments for viruses using Clam. To set this up, first install clamav\-data\-empty, clamav\-server, clamav\-server\-systemd and clamav\-update. .sp Then edit /etc/freshclam.conf, removing the Example line and run freshclam once to get an up to date database. .sp 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. .sp Then start the clamd service and set VIRUS_SCAN_ATTACHMENTS = True in the Pagure configuration. .SH INSTALLING PAGURE'S MILTER .sp A milter is a script that is ran by a Mail Transfer Agent (\fI\%MTA\fP) upon receiving an email via either a network or an unix socket. .sp If you want more information feel free to check out the corresponding page on wikipedia: \fI\%https://en.wikipedia.org/wiki/Milter\fP\&. .SS Configure your system .INDENT 0.0 .IP \(bu 2 Install the required dependencies .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C python\-pymilter .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 We ship a systemd unit file for pagure_milter but we welcome patches for scripts for other init systems. .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 It also requires a MTA, we used postfix. .UNINDENT .UNINDENT .INDENT 0.0 .IP \(bu 2 Create an alias \fBreply\fP .UNINDENT .sp This can be done in \fB/etc/aliases\fP, for example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C reply: /dev/null .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .IP \(bu 2 Activate the ability of your MTA, to split users based on the character \fB+\fP\&. This way all the emails sent to \fBreply+...@example.com\fP will be forwarded to your alias for \fBreply\fP\&. .UNINDENT .sp In postfix this is done via: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C recipient_delimiter = + .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .IP \(bu 2 Hook the milter in the MTA .UNINDENT .sp In postfix this is done via: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C non_smtpd_milters = unix:/var/run/pagure/paguresock smtpd_milters = unix:/var/run/pagure/paguresock .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .IP \(bu 2 Install the files of the milter as follow: .UNINDENT .TS center; |l|l|. _ T{ Source T} T{ Destination T} _ T{ \fBpagure\-milters/comment_email_milter.py\fP T} T{ \fB/usr/share/pagure/comment_email_milter.py\fP T} _ T{ \fBpagure\-milters/milter_tempfile.conf\fP T} T{ \fB/usr/lib/tmpfiles.d/pagure\-milter.conf\fP T} _ T{ \fBpagure\-milters/pagure_milter.service\fP T} T{ \fB/etc/systemd/system/pagure_milter.service\fP T} _ .TE .sp The first file is the script of the milter itself. .sp 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. .sp The third file is the systemd service file. .INDENT 0.0 .IP \(bu 2 Activate the service and ensure it\(aqs started upon boot: .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C systemctl enable pagure_milter systemctl start pagure_milter .ft P .fi .UNINDENT .UNINDENT .SH INSTALLING PAGURE'S EVENTSOURCE SERVER .sp Eventsource or Server Sent Events are messages sent from a server to a web browser. It allows one to refresh a page \(dqlive\(dq, ie, without the need to reload it entirely. .SS Configure your system .sp The eventsource server is easy to set\-up. .INDENT 0.0 .IP \(bu 2 Install the required dependencies .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C python\-redis python\-trololio .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 We ship a systemd unit file for pagure_milter but we welcome patches for scripts for other init systems. .UNINDENT .UNINDENT .INDENT 0.0 .IP \(bu 2 Install the files of the SSE server as follow: .UNINDENT .TS center; |l|l|. _ T{ Source T} T{ Destination T} _ T{ \fBpagure\-ev/pagure_stream_server.py\fP T} T{ \fB/usr/libexec/pagure\-ev/pagure_stream_server.py\fP T} _ T{ \fBpagure\-ev/pagure_ev.service\fP T} T{ \fB/etc/systemd/system/pagure_ev.service\fP T} _ .TE .sp The first file is the script of the SSE server itself. .sp The second file is the systemd service file. .INDENT 0.0 .IP \(bu 2 Finally, activate the service and ensure it\(aqs started upon boot: .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C systemctl enable redis systemctl start redis systemctl enable pagure_ev systemctl start pagure_ev .ft P .fi .UNINDENT .UNINDENT .SH INSTALLING PAGURE'S WEB-HOOKS NOTIFICATION SYSTEM .sp Web\-hooks are a notification system upon which a system makes a http POST request with some data upon doing an action. This allows notifying a system that an action has occurred. .sp If you want more information feel free to check out the corresponding page on wikipedia: \fI\%https://en.wikipedia.org/wiki/Webhook\fP\&. .SS Configure your system .INDENT 0.0 .IP \(bu 2 Install the required dependencies .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C python\-redis python\-trololio .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 We ship a systemd unit file for pagure_webhook but we welcome patches for scripts for other init systems. .UNINDENT .UNINDENT .INDENT 0.0 .IP \(bu 2 Install the files of the web\-hook server as follow: .UNINDENT .TS center; |l|l|. _ T{ Source T} T{ Destination T} _ T{ \fBpagure\-webhook/pagure\-webhook\-server.py\fP T} T{ \fB/usr/libexec/pagure\-webhook/pagure\-webhook\-server.py\fP T} _ T{ \fBpagure\-webhook/pagure_webhook.service\fP T} T{ \fB/etc/systemd/system/pagure_webhook.service\fP T} _ .TE .sp The first file is the script of the web\-hook server itself. .sp The second file is the systemd service file. .INDENT 0.0 .IP \(bu 2 Activate the service and ensure it\(aqs started upon boot: .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C systemctl enable redis systemctl start redis systemctl enable pagure_webhook systemctl start pagure_webhook .ft P .fi .UNINDENT .UNINDENT .SH INSTALLING PAGURE-CI .sp A CI stands for \fI\%Continuous Integration\fP\&. Pagure can be configured to integrate results coming from CI services, such as \fI\%Jenkins\fP on pull\-request opened against the project. .SS Configure your system .INDENT 0.0 .IP \(bu 2 Install the required dependencies .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C python\-jenkins python\-redis python\-trololio .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 We ship a systemd unit file for pagure_ci but we welcome patches for scripts for other init systems. .UNINDENT .UNINDENT .INDENT 0.0 .IP \(bu 2 Install the files of pagure\-ci as follow: .UNINDENT .TS center; |l|l|. _ T{ Source T} T{ Destination T} _ T{ \fBpagure\-ci/pagure_ci_server.py\fP T} T{ \fB/usr/libexec/pagure\-ci/pagure_ci_server.py\fP T} _ T{ \fBpagure\-ci/pagure_ci.service\fP T} T{ \fB/etc/systemd/system/pagure_ci.service\fP T} _ .TE .sp 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. .sp The second file is the systemd service file. .INDENT 0.0 .IP \(bu 2 Configure your pagure instance to support CI, add the following to your configuration file .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C PAGURE_CI_SERVICES = [\(aqjenkins\(aq] .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .IP \(bu 2 Activate the service and ensure it\(aqs started upon boot: .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C systemctl enable redis systemctl start redis systemctl enable pagure_ci systemctl start pagure_ci .ft P .fi .UNINDENT .UNINDENT .SH INSTALLING PAGURE-LOADJSON .sp pagure\-loadjson is the service that updates the database based on the content of the JSON blob pushed into the ticket git repository (and in the future for pull\-requests as well). .SS Configure your system .INDENT 0.0 .IP \(bu 2 Install the required dependencies .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C python\-redis python\-trololio .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 We ship a systemd unit file for pagure_loadjson but we welcome patches for scripts for other init systems. .UNINDENT .UNINDENT .INDENT 0.0 .IP \(bu 2 Install the files of pagure\-loadjon as follow: .UNINDENT .TS center; |l|l|. _ T{ Source T} T{ Destination T} _ T{ \fBpagure\-loadjson/pagure_loadjson_server.py\fP T} T{ \fB/usr/libexec/pagure\-loadjson/pagure_loadjson.py\fP T} _ T{ \fBpagure\-loadjson/pagure_loadjson.service\fP T} T{ \fB/etc/systemd/system/pagure_loadjson.service\fP T} _ .TE .sp 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. .sp The second file is the systemd service file. .INDENT 0.0 .IP \(bu 2 Activate the service and ensure it\(aqs started upon boot: .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C systemctl enable redis systemctl start redis systemctl enable pagure_loadjson systemctl start pagure_loadjson .ft P .fi .UNINDENT .UNINDENT .SH INSTALLING PAGURE-LOGCOM .sp pagure\-logcom is the service that updates the log table in the database for every commit made to the main branch of a repository allowing to build the calendar heatmap presented on every user\(aqs page. .SS Configure your system .INDENT 0.0 .IP \(bu 2 Install the required dependencies .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C python\-redis python\-trololio .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 We ship a systemd unit file for pagure_logcom but we welcome patches for scripts for other init systems. .UNINDENT .UNINDENT .INDENT 0.0 .IP \(bu 2 Install the files of pagure\-loadjon as follow: .UNINDENT .TS center; |l|l|. _ T{ Source T} T{ Destination T} _ T{ \fBpagure\-logcom/pagure_logcom_server.py\fP | \fB/usr/libexec/pagure\-logcom/pagure_logcom_server.py\fP T} _ T{ \fBpagure\-logcom/pagure_logcom.service\fP | \fB/etc/systemd/system/pagure_logcom.service\fP T} _ .TE .sp 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. .sp The second file is the systemd service file. .INDENT 0.0 .IP \(bu 2 Activate the service and ensure it\(aqs started upon boot: .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C systemctl enable redis systemctl start redis systemctl enable pagure_logcom systemctl start pagure_logcom .ft P .fi .UNINDENT .UNINDENT .SH CRON JOBS .sp Some actions in pagure are meant to the run via a cron job. .SS API key expiration reminder .sp One of the cron job sending reminder about API keys that are about to expire. It will send an email 10 days, then 5 days and finally the day before the key expires to the person who has created. .sp The cron job can be found in the sources in: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C files/api_key_expire_mail.py .ft P .fi .UNINDENT .UNINDENT .sp In the RPM it is installed in: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C /usr/share/pagure/api_key_expire_mail.py .ft P .fi .UNINDENT .UNINDENT .sp This cron job is meant to be run daily using a syntax similar to: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C 10 0 * * * root python /usr/share/pagure/api_key_expire_mail.py .ft P .fi .UNINDENT .UNINDENT .sp which will make the script run at 00:10 every day. .SH CONFIGURATION .sp Pagure offers a wide varieties of options that must or can be used to adjust its behavior. .sp All of these options can be edited or added to your configuration file. If you have installed pagure, this configuration file is likely located in \fB/etc/pagure/pagure.cfg\fP\&. Otherwise, it will depend on your setup/deployment. .SS Must options .sp Here are the options you must set up in order to get pagure running. .SS SECRET_KEY .sp This configuration key is used by flask to create the session. It should be kept secret and set as a long and random string. .SS SALT_EMAIL .sp This configuration key is used to ensure that when sending notifications to different users, each one of them has a different, unique and unfakeable \fBReply\-To\fP header. This header is then used by the milter to find out if the response received is a real one or a fake/invalid one. .SS DB_URL .sp This configuration key indicates to the framework how and where to connect to the database server. Pagure uses \fI\%SQLAchemy\fP to connect to a wide range of database server including MySQL, PostgreSQL, and SQLite. .sp Examples values: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C DB_URL = \(aqmysql://user:pass@host/db_name\(aq DB_URL = \(aqpostgres://user:pass@host/db_name\(aq DB_URL = \(aqsqlite:////var/tmp/pagure_dev.sqlite\(aq .ft P .fi .UNINDENT .UNINDENT .sp Defaults to \fBsqlite:////var/tmp/pagure_dev.sqlite\fP .SS APP_URL .sp This configuration key indicates the URL at which this pagure instance will be made available. .sp Defaults to: \fBhttp://localhost.localdomain/\fP .SS EMAIL_ERROR .sp Pagure sends email when it catches an unexpected error (which saves you from having to monitor the logs regularly; but if you like, the error is still present in the logs). This configuration key allows you to specify to which email address to send these error reports. .SS GIT_URL_SSH .sp This configuration key provides the information to the user on how to clone the git repos hosted on pagure via \fI\%SSH\fP\&. .sp The URL should end with a slash \fB/\fP\&. .sp Defaults to: \fB\(aqssh://git@llocalhost.localdomain/\(aq\fP .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 If you are using a custom setup for your deployment where every user has an account on the machine you may want to tweak this URL to include the username. If that is the case, you can use \fB{username}\fP in the URL and it will be expanded to the username of the user viewing the page when rendered. For example: \fB\(aqssh://{username}@pagure.org/\(aq\fP .UNINDENT .UNINDENT .SS GIT_URL_GIT .sp This configuration key provides the information to the user on how to clone the git repos hosted on pagure anonymously. This access can be granted via the \fBgit://\fP or \fBhttp(s)://\fP protocols. .sp The URL should end with a slash \fB/\fP\&. .sp Defaults to: \fB\(aqgit://localhost.localdomain/\(aq\fP .SS BROKER_URL .sp This configuration key is used to point celery to the broker to use. This is the broker that is used to communicate between the web application and its workers. .sp Defaults to: \fB\(aqredis://%s\(aq % APP.config[\(aqREDIS_HOST\(aq]\fP .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 See the \fI\%Redis options\fP for the \fBREDIS_HOST\fP configuration key .UNINDENT .UNINDENT .SS Repo Directories .sp Each project in pagure has 2 to 4 git repositories, depending on configuration of the Pagure instance (see below): .INDENT 0.0 .IP \(bu 2 the main repo for the code .IP \(bu 2 the doc repo showed in the doc server (optional) .IP \(bu 2 the ticket repo storing the metadata of the tickets (optional) .IP \(bu 2 the request repo storing the metadata of the pull\-requests .UNINDENT .sp 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. .SS GIT_FOLDER .sp This configuration key points to the folder where the git repos are stored. For every project, two to four repos are created: .INDENT 0.0 .IP \(bu 2 a repo with source code of the project .IP \(bu 2 a repo with documentation of the project (if \fBENABLE_DOCS\fP is \fBTrue\fP) .IP \(bu 2 a repo with metadata of tickets opened against the project (if \fBENABLE_TICKETS\fP is \fBTrue\fP) .IP \(bu 2 a repo with metadata of pull requests opened against the project .UNINDENT .sp Note that gitolite config value \fBGL_REPO_BASE\fP (if using gitolite 3) or \fB$REPO_BASE\fP (if using gitolite 2) \fBmust\fP have exactly the same value as \fBGIT_FOLDER\fP\&. .SS REMOTE_GIT_FOLDER .sp This configuration key points to the folder where the remote git repos (ie: not hosted on pagure) that someone used to open a pull\-request against a project hosted on pagure are stored. .SS UPLOAD_FOLDER_PATH .sp This configuration key points to the folder where user\-uploaded tarballs are stored and served from. .SS ATTACHMENTS_FOLDER .sp This configuration key points to the folder where attachments can be cached for easier access by the web\-server (allowing to not interact with the git repo having it to serve it). .SS UPLOAD_FOLDER_URL .sp Full URL to where the uploads are available. It is highly recommended for security reasons that this URL lives on a different domain than the main application (an entirely different domain, not just a sub\-domain). .sp Defaults to: \fB/releases/\fP, unsafe for production! .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 both \fIUPLOAD_FOLDER_PATH\fP and \fIUPLOAD_FOLDER_URL\fP must be specified for the upload release feature to work .UNINDENT .UNINDENT .SS SESSION_COOKIE_SECURE .sp When this is set to True, the session cookie will only be returned to the server via ssl (https). If you connect to the server via plain http, the cookie will not be sent. This prevents sniffing of the cookie contents. This may be set to False when testing your application but should always be set to True in production. .sp Defaults to: \fBFalse\fP for development, must be \fBTrue\fP in production with https. .SS SESSION_TYPE .sp Enables the \fI\%flask\-session\fP extension if set to a value other than \fBNone\fP\&. The \fBflask\-session\fP package needs to be installed and proper \fI\%configuration\fP needs to be included in the Pagure config file. .sp 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. .SS FROM_EMAIL .sp This configuration key specifies the email address used by this pagure instance when sending emails (notifications). .sp Defaults to: \fBpagure@localhost.localdomain\fP .SS DOMAIN_EMAIL_NOTIFICATIONS .sp This configuration key specifies the domain used by this pagure instance when sending emails (notifications). More precisely, it is used when building the \fBmsg\-id\fP header of the emails sent. .sp Defaults to: \fBlocalhost.localdomain\fP .SS VIRUS_SCAN_ATTACHMENTS .sp This configuration key configures whether attachments are scanned for viruses on upload. For more information, see the install.rst guide. .sp Defaults to: \fBFalse\fP .SS GIT_AUTH_BACKEND .sp This configuration key allows specifying which git auth backend to use. .sp 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. .sp By default pagure provides the following backends: .INDENT 0.0 .IP \(bu 2 \fItest_auth\fP: simple debugging backend printing and returning the string \fBCalled GitAuthTestHelper.generate_acls()\fP .IP \(bu 2 \fIgitolite2\fP: allows deploying pagure on the top of gitolite 2 .IP \(bu 2 \fIgitolite3\fP: allows deploying pagure on the top of gitolite 3 .IP \(bu 2 \fIpagure\fP: Pagure git auth implementation (using keyhelper.py and aclchecker.py) that is used via sshd AuthorizedKeysCommand .IP \(bu 2 \fIpagure_authorized_keys\fP: Pagure git auth implementation that writes to authorized_keys file .UNINDENT .sp Defaults to: \fBgitolite3\fP .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The option GITOLITE_BACKEND is the legacy name, and for backwards compatibility reasons will override this setting .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 These options can be expended, cf \fI\%Customize the gitolite configuration\fP\&. .UNINDENT .UNINDENT .SS Configure Pagure Auth .sp Pagure offers a simple, but extensible internal authentication mechanism for Git repositories. It relies on \fI\%SSH\fP for authentication. In other words, SSH lets you in and Pagure checks if you are allowed to do what you are trying to do once you are inside. .sp This authentication mechanism uses \fBkeyhelper.py\fP and \fBaclchecker.py\fP to check the Pagure database for user registered SSH keys to do the authentication. .sp The integrated authentication mechanism has two modes of operation: one where it is configured as the \fBAuthorizedKeysCommand\fP for the SSH user (preferred) and one where it is configured to manage the \fBauthorized_keys\fP file for the SSH user. .sp In the preferred mode, when you attempt to do an action with a remote Git repo over SSH (e.g. \fBgit clone ssh://git@localhost.localdomain/repository.git\fP), 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\(aqs \fBsshd_config\fP file to use it. .sp To use this variant, set the following in \fBpagure.cfg\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C GIT_AUTH_BACKEND = \(dqpagure\(dq HTTP_REPO_ACCESS_GITOLITE = None SSH_KEYS_USERNAME_EXPECT = \(dqgit\(dq SSH_COMMAND_NON_REPOSPANNER = ([ \(dq/usr/bin/%(cmd)s\(dq, \(dq/srv/git/repositories/%(reponame)s\(dq, ], {\(dqGL_USER\(dq: \(dq%(username)s\(dq}) .ft P .fi .UNINDENT .UNINDENT .sp Setting the following in \fB/etc/ssh/sshd_config\fP is also required: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C Match User git AuthorizedKeysCommand /usr/libexec/pagure/keyhelper.py \(dq%u\(dq \(dq%h\(dq \(dq%t\(dq \(dq%f\(dq AuthorizedKeysCommandUser git .ft P .fi .UNINDENT .UNINDENT .sp If you do not have the ability to modify the sshd configuration to set up the \fBpagure\fP backend, then you need to use the \fBpagure_authorized_keys\fP alternative backend. This backend will write to the git user\(aqs \fBauthorized_keys\fP 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. .sp To use this variant, enable the \fBpagure_authorized_keys_worker\fP service and set the following to \fBpagure.cfg\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C SSH_FOLDER = \(dq/srv/git/.ssh\(dq GIT_AUTH_BACKEND = \(dqpagure_authorized_keys\(dq HTTP_REPO_ACCESS_GITOLITE = None SSH_COMMAND_NON_REPOSPANNER = ([ \(dq/usr/bin/%(cmd)s\(dq, \(dq/srv/git/repositories/%(reponame)s\(dq, ], {\(dqGL_USER\(dq: \(dq%(username)s\(dq}) .ft P .fi .UNINDENT .UNINDENT .SS Configure Gitolite .sp Pagure can use \fI\%gitolite\fP as an authorization layer. Gitolite relies on \fI\%SSH\fP for the authentication. In other words, SSH lets you in and gitolite checks if you are allowed to do what you are trying to do once you are inside. .sp 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 \fI\%Customize the gitolite configuration\fP). .sp Using Gitolite also requires setting the following in \fBpagure.cfg\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C HTTP_REPO_ACCESS_GITOLITE = \(dq/usr/share/gitolite3/gitolite\-shell\(dq SSH_COMMAND_NON_REPOSPANNER = ( [ \(dq/usr/share/gitolite3/gitolite\-shell\(dq, \(dq%(username)s\(dq, \(dq%(cmd)s\(dq, \(dq%(reponame)s\(dq, ], {}, ) .ft P .fi .UNINDENT .UNINDENT .sp This ensures that the Gitolite environment is used for interacting with Git repositories. Further customizations are listed below. .SS \fBgitolite 2 and 3\fP .SS GITOLITE_HOME .sp This configuration key points to the home directory of the user under which gitolite is ran. .SS GITOLITE_KEYDIR .sp This configuration key points to the folder where gitolite stores and accesses the public SSH keys of all the user have access to the server. .sp 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. .SS GITOLITE_CONFIG .sp This configuration key points to the gitolite.conf file where pagure writes the gitolite repository access configuration. .SS GITOLITE_CELERY_QUEUE .sp This configuration is useful for large pagure deployment where recompiling the gitolite config file can take a long time. By default the compilation of gitolite\(aqs configuration file is done by the pagure_worker, which spawns by default 4 concurrent workers. If it takes a while to recompile the gitolite configuration file, these workers may be stepping on each others\(aq toes. In this situation, this configuration key allows you to direct the messages asking for the gitolite configuration file to be compiled to a different queue which can then be handled by a different service/worker. .sp Pagure provides a \fBpagure_gitolite_worker.service\fP systemd service file pre\-configured to handles these messages if this configuration key is set to \fBgitolite_queue\fP\&. .SS \fBgitolite 2 only\fP .SS GL_RC .sp This configuration key points to the file \fBgitolite.rc\fP used by gitolite to record who has access to what (ie: who has access to which repo/branch). .SS GL_BINDIR .sp This configuration key indicates the folder in which the gitolite tools can be found. It can be as simple as \fB/usr/bin/\fP if the tools have been installed using a package manager or something like \fB/opt/bin/\fP for a more custom install. .SS \fBgitolite 3 only\fP .SS GITOLITE_HAS_COMPILE_1 .sp By setting this configuration key to \fBTrue\fP, you can turn on using the gitolite \fBcompile\-1\fP binary. This speeds up gitolite task when it recompiles configuration after new project is created. In order to use this, you need to have the \fBcompile\-1\fP gitolite command. .sp There are two ways to have it, .INDENT 0.0 .IP 1. 3 You distribution already has the file installed for you and you can then just use it. .IP 2. 3 You need to download and install it yourself. We are describing what needs to be done for this here below. .UNINDENT .sp Installing the \fBcompile\-1\fP command: .INDENT 0.0 .IP \(bu 2 You also have to make sure that your distribution of gitolite contains \fI\%patch\fP which makes gitolite respect \fBALLOW_ORPHAN_GL_CONF\fP configuration variable, if this patch isn\(aqt already present, you will have to make the change yourself. .IP \(bu 2 In your \fBgitolite.rc\fP set \fBALLOW_ORPHAN_GL_CONF\fP to \fB1\fP (you may have to add it yourself). .IP \(bu 2 Still in your \fBgitolite.rc\fP file, uncomment \fBLOCAL_CODE\fP file and set it to a full path of a directory that you choose (for example \fB/usr/local/share/gitolite3\fP). .IP \(bu 2 Create a subdirectory \fBcommands\fP under the path you picked for \fBLOCAL_CODE\fP (in our example, you will need to do: \fBmkdir \-p /usr/local/share/gitolite3/commands\fP) .IP \(bu 2 Finally, install the \fBcompile\-1\fP command in this \fBcommands\fP subdirectory If your installation doesn\(aqt ship this file, you can \fI\%download it\fP\&. (Ensure the file is executable, otherwise gitolite will not find it) .UNINDENT .sp Defaults to: \fBFalse\fP .SS EventSource options .SS EVENTSOURCE_SOURCE .sp This configuration key indicates the URL at which the EventSource server is available. If not defined, pagure will behave as if there are no EventSource server running. .SS EVENTSOURCE_PORT .sp This configuration key indicates the port at which the EventSource server is running. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The EventSource server requires a redis server (see \fBRedis options\fP below) .UNINDENT .UNINDENT .SS Web\-hooks notifications .SS WEBHOOK .sp This configuration key allows turning on or off web\-hooks notifications for this pagure instance. .sp Defaults to: \fBFalse\fP\&. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The Web\-hooks server requires a redis server (see \fBRedis options\fP below) .UNINDENT .UNINDENT .SS Redis options .SS REDIS_HOST .sp This configuration key indicates the host at which the \fI\%redis\fP server is running. .sp Defaults to: \fB0.0.0.0\fP\&. .SS REDIS_PORT .sp This configuration key indicates the port at which the redis server can be contacted. .sp Defaults to: \fB6379\fP\&. .SS REDIS_DB .sp This configuration key indicates the name of the redis database to use for communicating with the EventSource server. .sp Defaults to: \fB0\fP\&. .SS Authentication options .SS ADMIN_GROUP .sp List of groups, either local or remote (if the openid server used supports the group extension), that are the site admins. These admins can regenerate the gitolite configuration, the ssh key files, and the hook\-token for every project as well as manage users and groups. .SS PAGURE_ADMIN_USERS .sp List of local users that are the site admins. These admins have the same rights as the users in the admin groups listed above as well as admin rights to all projects hosted on this pagure instance. .SS Celery Queue options .sp In order to help prioritize between tasks having a direct impact on the user experience and tasks needed to be run on the background but not directly impacting the users, we have split the generic tasks triggered by the web application into three possible queues: Fast, Medium, Slow. If none of these options are set, a single queue will be used for all tasks. .SS FAST_CELERY_QUEUE .sp This configuration key can be used to specify a dedicated queue for tasks that are triggered by the web frontend and need to be processed quickly for the best user experience. .sp This will be used for tasks such as creating a new project, forking or merging a pull\-request. .sp Defaults to: \fBNone\fP\&. .SS MEDIUM_CELERY_QUEUE .sp This configuration key can be used to specify a dedicated queue for tasks that are triggered by the web frontend and need to be processed but aren\(aqt critical for the best user experience. .sp This will be used for tasks such as updating a file in a git repository. .sp Defaults to: \fBNone\fP\&. .SS SLOW_CELERY_QUEUE .sp This configuration key can be used to specify a dedicated queue for tasks that are triggered by the web frontend, are slow and do not impact the user experience in the user interface. .sp This will be used for tasks such as updating the ticket git repo based on the content posted in the user interface. .sp Defaults to: \fBNone\fP\&. .SS Stomp Options .sp Pagure integration with Stomp allows you to emit messages to any stomp\-compliant message bus. .SS STOMP_NOTIFICATIONS .sp This configuration key can be used to turn on or off notifications via \fI\%stomp protocol\fP\&. All other stomp\-related settings don\(aqt need to be present if this is set to \fBFalse\fP\&. .sp Defaults to: \fBFalse\fP\&. .SS STOMP_BROKERS .sp List of 2\-tuples with broker domain names and ports. For example \fB[(\(aqprimary.msg.bus.com\(aq, 6543), (\(aqbackup.msg.bus.com\(ga, 6543)]\fP\&. .SS STOMP_HIERARCHY .sp Base name of the hierarchy to emit messages to. For example \fB/queue/some.hierarchy.\fP\&. Note that this \fBmust\fP end with a dot. Pagure will append queue names such as \fBproject.new\fP to this value, resulting in queue names being e.g. \fB/queue/some.hierarchy.project.new\fP\&. .SS STOMP_SSL .sp Whether or not to use SSL when connecting to message brokers. .sp Defaults to: \fBFalse\fP\&. .SS STOMP_KEY_FILE .sp Absolute path to key file for SSL connection. Only required if \fBSTOMP_SSL\fP is set to \fBTrue\fP\&. .SS STOMP_CERT_FILE .sp Absolute path to certificate file for SSL connection. Only required if \fBSTOMP_SSL\fP is set to \fBTrue\fP\&. .SS STOMP_CREDS_PASSWORD .sp Password for decoding \fBSTOMP_CERT_FILE\fP and \fBSTOMP_KEY_FILE\fP\&. Only required if \fBSTOMP_SSL\fP is set to \fBTrue\fP and credentials files are password\-encoded. .SS ALWAYS_STOMP_ON_COMMITS .sp This configuration key can be used to enforce \fI\%stomp\fP notifications on commits made on all projects in a pagure instance. .sp Defaults to: \fBFalse\fP\&. .SS API token ACLs .SS ACLS .sp This configuration key lists all the ACLs that can be associated with an API token with a short description of what the ACL allows one to do. This key it not really meant to be changed unless you really know what you are doing. .SS USER_ACLS .sp This configuration key can be used to list which of the ACLs listed in \fBACLS\fP can be associated with an API token of a project in the (web) user interface. .sp Use this configuration key in combination with \fBADMIN_API_ACLS\fP to disable certain ACLs for users while allowing admins to generate keys with them. .INDENT 0.0 .TP .B Defaults to: \fB[key for key in ACLS.keys() if key != \(aqgenerate_acls_project\(aq]\fP (ie: all the ACLs in \fBACLS\fP except for \fBgenerate_acls_project\fP) .UNINDENT .SS ADMIN_API_ACLS .sp This configuration key can be used to list which of the ACLs listed in \fBACLS\fP can be generated by the \fBpagure\-admin\fP CLI tool by admins. .sp Defaults to: \fB[\(aqissue_comment\(aq, \(aqissue_create\(aq, \(aqissue_change_status\(aq, \(aqpull_request_flag\(aq, \(aqpull_request_comment\(aq, \(aqpull_request_merge\(aq, \(aqgenerate_acls_project\(aq, \(aqcommit_flag\(aq, \(aqcreate_branch\(aq]\fP .SS CROSS_PROJECT_ACLS .sp This configuration key can be used to list which of the ACLs listed in \fBACLS\fP can be associated with a project\-less API token in the (web) user interface. These project\-less API tokens can be generated in the user\(aqs settings page and allows action in multiple projects instead of being restricted to a specific one. .sp Defaults to: \fB[\(aqcreate_project\(aq, \(aqfork_project\(aq, \(aqmodify_project\(aq]\fP .SS Optional options .SS Theming .SS THEME .sp This configuration key allows you to specify the theme to be used. The string specified is the name of the theme directory in \fBpagure/themes/\fP .sp For more information about theming see the \fI\%Theming Guide\fP .sp Default options: .INDENT 0.0 .IP \(bu 2 \fBchameleon\fP The OpenSUSE theme for pagure .IP \(bu 2 \fBdefault\fP The default theme for pagure .IP \(bu 2 \fBpagureio\fP The theme used at \fI\%https://pagure.io\fP .IP \(bu 2 \fBsrcfpo\fP The theme used at \fI\%https://src.fedoraproject.org\fP .UNINDENT .sp Defaults to: \fBdefault\fP .SS Git repository templates .SS PROJECT_TEMPLATE_PATH .sp This configuration key allows you to specify the path to a git repository to use as a template when creating new repository for new projects. This template will not be used for forks nor any of the git repository but the one used for the sources (ie: it will not be used for the tickets, requests or docs repositories). .SS FORK_TEMPLATE_PATH .sp This configuration key allows you to specify the path to a git repository to use as a template when creating new repository for new forks. This template will not be used for any of the git repository but the one used for the sources of forks (ie: it will not be used for the tickets, requests or docs repositories). .SS SSH_KEYS .sp It is a good practice to publish the fingerprint and public SSH key of a server you provide access to. Pagure offers the possibility to expose this information based on the values set in the configuration file, in the \fBSSH_KEYS\fP configuration key. .sp See the \fI\%SSH hostkeys/Fingerprints page on pagure.io\fP\&. .sp Where \fI\fP and \fI\fP must be replaced by your values. .SS CSP_HEADERS .sp Content Security Policy (CSP) is a computer security standard introduced to prevent cross\-site scripting (XSS), clickjacking and other code injection attacks resulting from execution of malicious content in the trusted web page context .sp Source: \fI\%https://en.wikipedia.org/wiki/Content_Security_Policy\fP .sp Defaults to: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C CSP_HEADERS = ( \(dqdefault\-src \(aqself\(aq https:; \(dq \(dqscript\-src \(aqself\(aq \(aqnonce\-{nonce}\(aq; \(dq \(dqstyle\-src \(aqself\(aq \(aqnonce\-{nonce}\(aq\(dq ) .ft P .fi .UNINDENT .UNINDENT .sp Where \fB{nonce}\fP is dynamically set by pagure. .SS LOGGING_GIT_HOOKS .sp This configuration key allows to have a different logging configuration for the web application and the git hooks. .sp 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 \fBLOGGING\fP here below). .sp Defaults to: \fBNone\fP\&. .SS LOGGING .sp This configuration key allows you to set up the logging of the application. It relies on the standard \fI\%python logging module\fP\&. .sp The default value is: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C LOGGING = { \(dqversion\(dq: 1, \(dqdisable_existing_loggers\(dq: False, \(dqformatters\(dq: { \(dqstandard\(dq: { \(dqformat\(dq: \(dq%(asctime)s [%(levelname)s] %(name)s: %(message)s\(dq }, \(dqemail_format\(dq: {\(dqformat\(dq: MSG_FORMAT}, }, \(dqfilters\(dq: {\(dqmyfilter\(dq: {\(dq()\(dq: ContextInjector}}, \(dqhandlers\(dq: { \(dqconsole\(dq: { \(dqformatter\(dq: \(dqstandard\(dq, \(dqclass\(dq: \(dqlogging.StreamHandler\(dq, \(dqstream\(dq: \(dqext://sys.stdout\(dq, }, \(dqauth_handler\(dq: { \(dqformatter\(dq: \(dqstandard\(dq, \(dqclass\(dq: \(dqlogging.StreamHandler\(dq, \(dqstream\(dq: \(dqext://sys.stdout\(dq, }, \(dqemail\(dq: { \(dqlevel\(dq: \(dqERROR\(dq, \(dqformatter\(dq: \(dqemail_format\(dq, \(dqclass\(dq: \(dqlogging.handlers.SMTPHandler\(dq, \(dqmailhost\(dq: \(dqlocalhost\(dq, \(dqfromaddr\(dq: \(dqpagure@localhost\(dq, \(dqtoaddrs\(dq: \(dqroot@localhost\(dq, \(dqsubject\(dq: \(dqERROR on pagure\(dq, \(dqfilters\(dq: [\(dqmyfilter\(dq], }, }, # The root logger configuration; this is a catch\-all configuration # that applies to all log messages not handled by a different logger \(dqroot\(dq: {\(dqlevel\(dq: \(dqINFO\(dq, \(dqhandlers\(dq: [\(dqconsole\(dq]}, \(dqloggers\(dq: { \(dqpagure\(dq: { \(dqhandlers\(dq: [\(dqconsole\(dq], \(dqlevel\(dq: \(dqDEBUG\(dq, \(dqpropagate\(dq: True, }, \(dqpagure_auth\(dq: { \(dqhandlers\(dq: [\(dqauth_handler\(dq], \(dqlevel\(dq: \(dqDEBUG\(dq, \(dqpropagate\(dq: False, }, \(dqflask\(dq: { \(dqhandlers\(dq: [\(dqconsole\(dq], \(dqlevel\(dq: \(dqINFO\(dq, \(dqpropagate\(dq: False, }, \(dqsqlalchemy\(dq: { \(dqhandlers\(dq: [\(dqconsole\(dq], \(dqlevel\(dq: \(dqWARN\(dq, \(dqpropagate\(dq: False, }, \(dqbinaryornot\(dq: { \(dqhandlers\(dq: [\(dqconsole\(dq], \(dqlevel\(dq: \(dqWARN\(dq, \(dqpropagate\(dq: True, }, \(dqMARKDOWN\(dq: { \(dqhandlers\(dq: [\(dqconsole\(dq], \(dqlevel\(dq: \(dqWARN\(dq, \(dqpropagate\(dq: True, }, \(dqPIL\(dq: {\(dqhandlers\(dq: [\(dqconsole\(dq], \(dqlevel\(dq: \(dqWARN\(dq, \(dqpropagate\(dq: True}, \(dqchardet\(dq: { \(dqhandlers\(dq: [\(dqconsole\(dq], \(dqlevel\(dq: \(dqWARN\(dq, \(dqpropagate\(dq: True, }, \(dqpagure.lib.encoding_utils\(dq: { \(dqhandlers\(dq: [\(dqconsole\(dq], \(dqlevel\(dq: \(dqWARN\(dq, \(dqpropagate\(dq: False, }, }, } .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 as you can see there is an \fBemail\fP handler defined. It\(aqs not used anywhere by default but you can use it to get report of errors by email and thus monitor your pagure instance. To do this the easiest is to set, on the \fBroot\fP logger: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C \(aqhandlers\(aq: [\(aqconsole\(aq, \(aqemail\(aq], .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The \fBpagure_auth\fP logger is a special one logging all activities regarding read/write access to git repositories. It will be a pretty important log for auditing if needed. You can separate this log into its own file if you like by using the following handler: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C \(dqauth_handler\(dq: { \(dqformatter\(dq: \(dqstandard\(dq, \(dqclass\(dq: \(dqlogging.handlers.TimedRotatingFileHandler\(dq, \(dqfilename\(dq: \(dq/var/log/pagure/pagure_auth.log\(dq, \(dqbackupCount\(dq: 10, \(dqwhen\(dq: \(dqmidnight\(dq, \(dqutc\(dq: True, }, .ft P .fi .UNINDENT .UNINDENT .sp This snippet will automatically make the logs rotate at midnight each day, keep the logs for 10 days and use UTC as timezone for the logs. Depending on how your pagure instance is set\-up, you may have to tweak the filesystem permissions on the folder and file so the rotation works properly. .UNINDENT .UNINDENT .SS ITEM_PER_PAGE .sp This configuration key allows you to configure the length of a page by setting the number of items on the page. Items can be commits, users, groups, or projects for example. .sp Defaults to: \fB50\fP\&. .SS PR_TARGET_MATCHING_BRANCH .sp If set to \fBTrue\fP, the default target branch for all pull requests in UI is the branch that is longest substring of the branch that the pull request is created from. For example, a \fBmybranch\fP branch in original repo will be the default target of a pull request from branch \fBmybranch\-feature\-1\fP in a fork when opening a new pull request. If this is set to \fBFalse\fP, the default branch of the repo will be the default target of all pull requests. .sp Defaults to: \fBFalse\fP\&. .SS SSH_ACCESS_GROUPS .sp Some instances of pagure are deployed in such a way that only the members of certain groups are allowed to commit via ssh. This configuration key allows to specify which groups have commit access and thus let pagure hide the ssh URL from the drop\-down \(dqClone\(dq menu for all the person who are not in one of these groups. If this configuration key is not defined or left empty, it is assume that there is no such group restriction and everyone can commit via ssh (default behavior). .sp Defaults to: \fB[]\fP .SS SMTP configuration .SS SMTP_SERVER .sp This configuration key specifies the SMTP server to use when sending emails. .sp Defaults to: \fBlocalhost\fP\&. .sp See also the SMTP_STARTTLS section. .SS SMTP_PORT .sp This configuration key specifies the SMTP server port. .sp 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). .sp Defaults to: \fB25\fP .SS SMTP_SSL .sp This configuration key specifies whether the SMTP connections should be secured over SSL. .sp Defaults to: \fBFalse\fP .SS SMTP_STARTTLS .sp This configuration key specifies instructs pagure to starts connecting to the SMTP server via a \fIstarttls\fP command. .sp When enabling STARTTLS in conjunction with a local smtp server, you should replace \fBlocalhost\fP with a host name that is included in the server\(aqs certificate. If the server only relays messages originating from \fBlocalhost\fP, then you should also ensure that the above host name resolves to the same tcp address as \fBlocalhost\fP, for instance by adding an appropriate record to \fI/etc/hosts\fP\&. .sp Defaults to: \fBFalse\fP .SS SMTP_KEYFILE .sp This configuration key allows to specify a key file to be used in the \fIstarttls\fP command when connecting to the smtp server. .sp Defaults to: \fBNone\fP .SS SMTP_CERTFILE .sp This configuration key allows to specify a certificate file to be used in the \fIstarttls\fP command when connecting to the smtp server. .sp Defaults to: \fBNone\fP .SS SMTP_USERNAME .sp This configuration key allows usage of SMTP with auth. .sp Note: Specify SMTP_USERNAME and SMTP_PASSWORD for using SMTP auth .sp Defaults to: \fBNone\fP .SS SMTP_PASSWORD .sp This configuration key allows usage of SMTP with auth. .sp Note: Specify SMTP_USERNAME and SMTP_PASSWORD for using SMTP auth .sp Defaults to: \fBNone\fP .SS SHORT_LENGTH .sp This configuration key specifies the length of the commit ids or file hex displayed in the user interface. .sp Defaults to: \fB6\fP\&. .SS BLACKLISTED_PROJECTS .sp This configuration key specifies a list of project names that are forbidden. This list is used for example to avoid conflicts at the URL level between the static files located under \fB/static/\fP and a project that would be named \fBstatic\fP and thus be located at \fB/static\fP\&. .sp Defaults to: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C [ \(aqstatic\(aq, \(aqpv\(aq, \(aqreleases\(aq, \(aqnew\(aq, \(aqapi\(aq, \(aqsettings\(aq, \(aqlogout\(aq, \(aqlogin\(aq, \(aqusers\(aq, \(aqgroups\(aq, \(aqabout\(aq ] .ft P .fi .UNINDENT .UNINDENT .SS CHECK_SESSION_IP .sp This configuration key specifies whether to check the user\(aqs IP address when retrieving its session. This makes things more secure but under certain setups it might not work (for example if there are proxies in front of the application). .sp Defaults to: \fBTrue\fP\&. .SS PAGURE_AUTH .sp This configuration key specifies which authentication method to use. Valid options are \fBfas\fP, \fBopenid\fP, \fBoidc\fP, or \fBlocal\fP\&. .INDENT 0.0 .IP \(bu 2 \fBfas\fP uses the Fedora Account System \fIFAS \fP to provide user authentication and enforces that users sign the FPCA. .IP \(bu 2 \fBopenid\fP uses OpenID authentication. Any provider may be used by changing the FAS_OPENID_ENDPOINT configuration key. By default FAS (without FPCA) will be used. .IP \(bu 2 \fBoidc\fP enables OpenID Connect using any provider. This provider requires the configuration options starting with \fBOIDC_\fP (see below) to be provided. .IP \(bu 2 \fBlocal\fP causes pagure to use the local pagure database for user management. .UNINDENT .sp Defaults to: \fBlocal\fP\&. .SS OIDC Settings .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Pagure uses \fI\%flask\-oidc\fP to support OIDC authentication. This extension has a \fI\%number of configuration keys\fP that may be useful depending on your set\-up .UNINDENT .UNINDENT .SS OIDC_CLIENT_SECRETS .sp Provide a path to client secrets file on local filesystem. This file can be obtained from your OpenID Connect identity provider. Note that some providers don\(aqt fill in \fBuserinfo_uri\fP\&. If that is the case, you need to add it to the secrets file manually. .SS OIDC_ID_TOKEN_COOKIE_SECURE .sp When this is set to True, the cookie with OpenID Connect Token will only be returned to the server via ssl (https). If you connect to the server via plain http, the cookie will not be sent. This prevents sniffing of the cookie contents. This may be set to False when testing your application but should always be set to True in production. .sp Defaults to: \fBTrue\fP for production with https, can be set to \fBFalse\fP for convenient development. .SS OIDC_SCOPES .sp List of \fIOpenID Connect scopes http://openid.net/specs/openid\-connect\-core\-1_0.html#ScopeClaims\fP to request from identity provider. .SS OIDC_PAGURE_EMAIL .sp Name of key of user\(aqs email in userinfo JSON returned by identity provider. .SS OIDC_PAGURE_FULLNAME .sp Name of key of user\(aqs full name in userinfo JSON returned by identity provider. .SS OIDC_PAGURE_USERNAME .sp Name of key of user\(aqs preferred username in userinfo JSON returned by identity provider. .SS OIDC_PAGURE_SSH_KEY .sp Name of key of user\(aqs ssh key in userinfo JSON returned by identity provider. .SS OIDC_PAGURE_GROUPS .sp Name of key of user\(aqs groups in userinfo JSON returned by identity provider. .SS OIDC_PAGURE_USERNAME_FALLBACK .sp This specifies fallback for getting username assuming \fBOIDC_PAGURE_USERNAME\fP is empty \- can be \fBemail\fP (to use the part before \fB@\fP) or \fBsub\fP (IdP\-specific user id, can be a nickname, email or a numeric ID depending on identity provider). .SS IP_ALLOWED_INTERNAL .sp This configuration key specifies which IP addresses are allowed to access the internal API endpoint. These endpoints are accessed by the milters for example and allow performing actions in the name of someone else which is sensitive, thus the origin of the request using these endpoints is validated. .sp Defaults to: \fB[\(aq127.0.0.1\(aq, \(aqlocalhost\(aq, \(aq::1\(aq]\fP\&. .SS MAX_CONTENT_LENGTH .sp This configuration key specifies the maximum file size allowed when uploading content to pagure (for example, screenshots to a ticket). .sp Defaults to: \fB4 * 1024 * 1024\fP which corresponds to 4 megabytes. .SS ENABLE_TICKETS .sp This configuration key activates or deactivates the ticketing system for all the projects hosted on this pagure instance. .sp Defaults to: \fBTrue\fP .SS ENABLE_TICKETS_NAMESPACE .sp This configuration key can be used to restrict the namespace in which the ticketing system is enabled. So if your pagure instance has \fBENABLE_TICKETS\fP as \fBTrue\fP and sets \fBENABLE_TICKETS_NAMESPACE\fP to \fB[\(aqtests\(aq, \(aqinfra\(aq]\fP only the projects opened in these two namespaces will have the ticketing system enabled. All the other namespaces will not. .sp Defaults to: \fB[]\fP .SS ENABLE_DOCS .sp This configuration key activates or deactivates creation of git repos for documentation for all the projects hosted on this pagure instance. .sp Defaults to: \fBTrue\fP .SS ENABLE_NEW_PROJECTS .sp This configuration key permits or forbids creation of new projects via the user interface and the API of this pagure instance. .sp Defaults to: \fBTrue\fP .SS ENABLE_UI_NEW_PROJECTS .sp This configuration key permits or forbids creation of new projects via the user interface (only) of this pagure instance. It allows forbidding to create new project in the user interface while letting a set of trusted person to create projects via the API granted they have the API token with the corresponding ACL. .sp Defaults to: \fBTrue\fP .SS ENABLE_DEL_PROJECTS .sp This configuration key permits or forbids deletion of projects via the user interface of this pagure instance. .sp Defaults to: \fBTrue\fP .SS ENABLE_DEL_FORKS .sp This configuration key permits or forbids deletion of forks via the user interface of this pagure instance. .sp Defaults to: \fBENABLE_DEL_PROJECTS\fP .SS GIT_HOOK_DB_RO .sp This configuration key specifies if the git hook have a read\-only (RO) access to the database or not. Some pagure deployment provide an actual shell account on the host and thus the git hook called upon git push are executed under that account. If the user manages to by\-pass git and is able to access the configuration file, they could have access to \(dqprivate\(dq information. So in those deployments the git hooks have a specific configuration file with a database access that is read\-only, making pagure behave differently in those situations. .sp Defaults to: \fBFalse\fP .SS EMAIL_SEND .sp This configuration key enables or disables all email notifications for this pagure instance. This can be useful to turn off when developing on pagure, or for test or pre\-production instances. .sp Defaults to: \fBFalse\fP\&. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 This does not disable emails to the email address set in \fBEMAIL_ERROR\fP\&. .UNINDENT .UNINDENT .SS FEDMSG_NOTIFICATIONS .sp This configuration key can be used to turn on or off notifications via \fI\%fedmsg\fP\&. .sp Defaults to: \fBFalse\fP\&. .SS FEDORA_MESSAGING_NOTIFICATIONS .sp This configuration key can be used to turn on or off sending notifications via \fI\%fedora\-messaging\fP\&. .sp Defaults to: \fBFalse\fP\&. .SS ALWAYS_FEDMSG_ON_COMMITS .sp This configuration key can be used to enforce \fI\%fedmsg\fP notifications on commits made on all projects in a pagure instance. .sp Defaults to: \fBTrue\fP\&. .SS ALLOW_DELETE_BRANCH .sp This configuration keys enables or disables allowing users to delete git branches from the user interface. In sensible pagure instance you may want to turn this off and with a customized gitolite configuration you can prevent users from deleting branches in their git repositories. .sp Defaults to: \fBTrue\fP\&. .SS ALLOW_ADMIN_IGNORE_EXISTING_REPOS .sp This enables a checkbox \(dqIgnore existing repos\(dq for admins when creating a new project. When this is checkbox is checked, existing repositories will not cause project creation to fail. This could be used to assume responsibility of existing repositories. .sp Defaults to: \fBFalse\fP\&. .SS USERS_IGNORE_EXISTING_REPOS .sp List of users who can al create a project while ignoring existing repositories. .sp Defaults to: \fB[]\fP\&. .SS LOCAL_SSH_KEY .sp This configuration key can be used to let pagure administrate the user\(aqs ssh keys or have a third party tool do it for you. In most cases, it will be fine to let pagure handle it. .sp Defaults to \fBTrue\fP\&. .SS DEPLOY_KEY .sp This configuration key can be used to disable the deploy keys feature of an entire pagure instance. This feature enable to add extra public ssh keys that a third party could use to push to a project. .sp Defaults to \fBTrue\fP\&. .SS OLD_VIEW_COMMIT_ENABLED .sp In version 1.3, pagure changed its URL scheme to view the commit of a project in order to add support for pseudo\-namespaced projects. .sp For pagure instances older than 1.3, who care about backward compatibility, we added an endpoint \fBview_commit_old\fP 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. .sp 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. .sp Defaults to: \fBFalse\fP\&. .SS DISABLE_REMOTE_PR .sp In some pagure deployments remote pull requests need to be disabled due to legal / policy reasons. .sp Defaults to: \fBFalse\fP\&. .SS PAGURE_CI_SERVICES .sp Pagure can be configure to integrate results of a Continuous Integration (CI) service to pull\-requests open against a project. .sp To enable this integration, follow the documentation on how to install pagure\-ci and set this configuration key to \fB[\(aqjenkins\(aq]\fP (Jenkins being the only CI service supported at the moment). .sp Defaults to: \fBNone\fP\&. .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 Requires \fIRedis\fP to be configured and running. .UNINDENT .UNINDENT .SS INSTANCE_NAME .sp This allows giving a name to this running instance of pagure. The name is then used in the welcome screen shown upon first login. .sp Defaults to: \fBPagure\fP .SS ADMIN_EMAIL .sp This configuration key allows you to change the default administrator email which is displayed on the \(dqabout\(dq page. It can also be used elsewhere. .sp Defaults to: \fBroot@localhost.localdomain\fP .SS USER_NAMESPACE .sp This configuration key can be used to enforce that project are namespaced under the user\(aqs username, behaving in this way in a similar fashion as github.com or gitlab.com. .sp Defaults to: \fBFalse\fP .SS DOC_APP_URL .sp This configuration key allows you to specify where the documentation server is running (preferably in a different domain name entirely). If not set, the documentation page will show an error message saying that this pagure instance does not have a documentation server. .sp Defaults to: \fBNone\fP .SS PRIVATE_PROJECTS .sp This configuration key allows you to host private repositories. These repositories are visible only to the creator of the repository and to the users who are given access to the repository. No information is leaked about the private repository which means redis doesn\(aqt have the access to the repository and even fedmsg doesn\(aqt get any notifications. .sp Defaults to: \fBTrue\fP .SS EXCLUDE_GROUP_INDEX .sp This configuration key can be used to hide project an user has access to via one of the groups listed in this key. .sp 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\(aqs 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. .sp Defaults to: \fB[]\fP .SS TRIGGER_CI .sp A run of pagure\-ci can be manually triggered if some key sentences are added as comment to a pull\-request, either manually or via the \(dqRerun CI\(dq dropdown. This allows one to re\-run a test that failed due to some network outage or other unexpected issues unrelated to the test suite. .sp 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: \fB{\(dq\(dq: {\(dqname\(dq: \(dq\(dq, \(dqdescription\(dq: \(dq\(dq}}\fP .sp Sentences which have \fBNone\fP as value won\(aqt show up in the \(dqRerun CI\(dq dropdown. Additionally, it\(aqs possible to add a \fBrequires_project_hook_attr\fP key to the dict with data about a sentence. For example, having \fB\(dqrequires_project_hook_attr\(dq: (\(dqci_hook\(dq, \(dqactive_pr\(dq, True)\fP would make the \(dqRerun CI\(dq dropdown have a button for this specific CI only if the project has \fBci_hook\fP activated and its \fBactive_pr\fP value is \fBTrue\fP\&. .sp In versions before 5.2, this was a list containing just the sentences. .sp Defaults to: \fB{\(dqpretty please pagure\-ci rebuild\(dq: {\(dqname\(dq: \(dqDefault CI\(dq, \(dqdescription\(dq: \(dqRerun default CI\(dq}}\fP .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The sentences defined in this configuration key should be lower case only! .UNINDENT .UNINDENT .SS FLAG_STATUSES_LABELS .sp By default, Pagure has \fBsuccess\fP, \fBfailure\fP, \fBerror\fP, \fBpending\fP and \fBcanceled\fP statuses of PR and commit flags. This setting allows you to define a custom mapping of statuses to their respective Bootstrap labels. .SS FLAG_SUCCESS .sp Holds name of PR/commit flag that is considered a success. .sp Defaults to: \fBsuccess\fP .SS FLAG_FAILURE .sp Holds name of PR/commit flag that is considered a failure. .sp Defaults to: \fBfailure\fP .SS FLAG_PENDING .sp Holds name of PR/commit flag that is considered a pending state. .sp Defaults to: \fBpending\fP .SS EXTERNAL_COMMITTER .sp The external committer feature is a way to allow members of groups defined outside pagure (and provided to pagure upon login by the authentication system) to be consider committers on pagure. .sp This feature can give access to all the projects on the instance, all but some or just some. .sp Defaults to: \fB{}\fP .sp To give access to all the projects to a group named \fBfedora\-altarch\fP use a such a structure: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C EXTERNAL_COMMITTER = { \(aqfedora\-altarch\(aq: {} } .ft P .fi .UNINDENT .UNINDENT .sp To give access to all the projects but one (named \fBrpms/test\fP) to a group named \fBprovenpackager\fP use a such a structure: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C EXTERNAL_COMMITTER = { \(aqfedora\-altarch\(aq: {}, \(aqprovenpackager\(aq: { \(aqexclude\(aq: [\(aqrpms/test\(aq] } } .ft P .fi .UNINDENT .UNINDENT .sp To give access to just some projects (named \fBrpms/test\fP and \fBmodules/test\fP) to a group named \fBtesters\fP use a such a structure: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C EXTERNAL_COMMITTER = { \(aqfedora\-altarch\(aq: {}, \(aqprovenpackager\(aq: { \(aqexclude\(aq: [\(aqrpms/test\(aq] }, \(aqtesters\(aq: { \(aqrestrict\(aq: [\(aqrpms/test\(aq, \(aqmodules/test\(aq] } } .ft P .fi .UNINDENT .UNINDENT .SS REQUIRED_GROUPS .sp The required groups allows one to specify in which group an user must be to be added to a project with commit or admin access. .sp Defaults to: \fB{}\fP .sp Example configuration: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C REQUIRED_GROUPS = { \(aqrpms/kernel\(aq: [\(aqpackager\(aq, \(aqkernel\-team\(aq], \(aqmodules/*\(aq: [\(aqmodule\-packager\(aq, \(aqpackager\(aq], \(aqrpms/*\(aq: [\(aqpackager\(aq], \(aq*\(aq: [\(aqcontributor\(aq], } .ft P .fi .UNINDENT .UNINDENT .sp With this configuration (evaluated in the provided order): .INDENT 0.0 .IP \(bu 2 only users that are in the groups \fBpackager\fP and \fBkernel\-team\fP will be allowed to be added the \fBrpms/kernel\fP project (where \fBrpms\fP is the namespace and \fBkernel\fP the project name). .IP \(bu 2 only users that are in the groups \fBmodule\-packager\fP and \fBpackager\fP will be allowed to be added to projects in the \fBmodules\fP namespace. .IP \(bu 2 only users that are in the group \fBpackager\fP will be allowed to be added to projects in the \fBrpms\fP namespace. .IP \(bu 2 only users in the \fBcontributor\fP group will be allowed to be added to any project on this pagure instance. .UNINDENT .SS GITOLITE_PRE_CONFIG .sp This configuration key allows you to include some content at the \fItop\fP of the gitolite configuration file (such as some specific group definition), thus allowing to customize the gitolite configuration file with elements and information that are outside of pagure\(aqs control. .sp This can be used in combination with \fBGITOLITE_POST_CONFIG\fP to further customize gitolite\(aqs configuration file. It can also be used with \fBEXTERNAL_COMMITTER\fP to give commit access to git repos based on external information. .sp Defaults to: \fBNone\fP .SS GITOLITE_POST_CONFIG .sp This configuration key allows you to include some content at the \fIend\fP of the gitolite configuration file (such as some project definition or access), thus allowing to customize the gitolite configuration file with elements and information that are outside of pagure\(aqs control. .sp This can be used in combination with \fBGITOLITE_PRE_CONFIG\fP to further customize gitolite\(aqs configuration file. It can also be used with \fBEXTERNAL_COMMITTER\fP to give commit access to git repos based on external information. .sp Defaults to: \fBNone\fP .SS GIT_GARBAGE_COLLECT .sp This configuration key allows for explicit running of \fBgit gc \-\-auto\fP after every operation that adds new objects to any git repository \- that is after pushing and merging. The reason for having this functionality in Pagure is that gc is not guaranteed to be run by git after every object\-adding operation. .sp The garbage collection run by Pagure will respect git settings, so you can tweak \fBgc.auto\fP and \fBgc.autoPackLimit\fP 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 \fB/etc/gitconfig\fP\&. See \fI\%https://git\-scm.com/docs/git\-gc#git\-gc\-\-\-auto\fP for more details. .sp 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 \fIa lot\fP of metadata reads. .sp Note that the garbage collection is only run on repos that are not on repoSpanner. .sp Defaults to: \fBFalse\fP .SS CELERY_CONFIG .sp This configuration key allows you to tweak the configuration of celery for your needs. See the documentation about \fI\%celery configuration\fP for more information. .sp Defaults to: \fB{}\fP .SS CASE_SENSITIVE .sp This configuration key can be used to make this pagure instance case sensitive instead of its default: case\-insensitive. .sp Defaults to: \fBFalse\fP .SS PROJECT_NAME_REGEX .sp This configuration key can be used to customize the regular expression used to validate new project name. .sp Defaults to: \fB^[a\-zA\-z0\-9_][a\-zA\-Z0\-9\-_]*$\fP .SS APPLICATION_ROOT .sp This configuration key is used in the path of the cookie used by pagure. .sp Defaults to: \fB\(aq/\(aq\fP .SS ALLOWED_PREFIX .sp This configuration key can be used to specify a list of allowed namespaces that will not require creating a group for users to create projects in. .sp Defaults to: \fB[]\fP .SS ADMIN_SESSION_LIFETIME .sp This configuration key allows specifying the lifetime of the session during which the user won\(aqt have to re\-login for admin actions. In other words, the maximum time between which an user can access a project\(aqs settings page without re\-login. .sp Defaults to: \fBtimedelta(minutes=20)\fP .sp where timedelta comes from the python datetime module .SS BLACKLISTED_GROUPS .sp This configuration key can be used to blacklist some group names. .sp Defaults to: \fB[\(aqforks\(aq, \(aqgroup\(aq]\fP .SS ENABLE_GROUP_MNGT .sp This configuration key can be used to turn on or off managing (ie: creating a group, adding or removing users in that group) groups in this pagure instance. If turned off, groups and group members are to be managed outside of pagure and synced upon login. .sp Defaults to: \fBTrue\fP .SS ENABLE_USER_MNGT .sp This configuration key can be used to turn on or off managing users (adding or removing them from a project) in this pagure instance. If turned off, users are managed outside of pagure. .sp Defaults to: \fBTrue\fP .SS SESSION_COOKIE_NAME .sp This configuration key can be used to specify the name of the session cookie used by pagure. .sp Defaults to: \fB\(aqpagure\(aq\fP .SS SHOW_PROJECTS_INDEX .sp This configuration key can be used to specify what is shown in the index page of logged in users. .sp Defaults to: \fB[\(aqrepos\(aq, \(aqmyrepos\(aq, \(aqmyforks\(aq]\fP .SS EMAIL_ON_WATCHCOMMITS .sp By default pagure sends an email to every one watch commits on a project when a commit is made. However some pagure instances may be using a different notification mechanism on commits and thus may not want this feature to double the notifications received. This configuration key can be used to turn on or off email being sent to people watching commits on a project upon commits. .sp Defaults to: \fBTrue\fP .SS ALLOW_HTTP_PULL_PUSH .sp This configuration key controls whether any HTTP access to repositories is provided via the support for that that\(aqs embedded in Pagure. This provides HTTP pull access via /.git if nothing else serves this URL. .sp Defaults to: \fBTrue\fP .SS ALLOW_HTTP_PUSH .sp This configuration key controls whether pushing is possible via the HTTP interface. This is disabled by default, as it requires setting up an authentication mechanism on the webserver that sets REMOTE_USER. .sp Defaults to: \fBFalse\fP .SS HTTP_REPO_ACCESS_GITOLITE .sp This configuration key configures the path to the gitolite\-shell binary. If this is set to None, Git http\-backend is used directly. Only set this to \fBNone\fP if you intend to provide HTTP push access via Pagure, and are using a dynamic ACL backend. .sp Defaults to: \fB/usr/share/gitolite3/gitolite\-shell\fP .SS MIRROR_SSHKEYS_FOLDER .sp This configuration key specificies where pagure should store the ssh keys generated for the mirroring feature. This folder should be properly backed up and kept secure. .sp Defaults to: \fB/var/lib/pagure/sshkeys/\fP .SS LOG_ALL_COMMITS .sp This configuration key will make pagure log all commits pushed to all branches of all repositories instead of logging only the once that are pushed to the default branch. .sp Defaults to: \fBFalse\fP .SS DISABLE_MIRROR_IN .sp This configuration key allows a pagure instance to not support mirroring in projects (from third party git server). .sp Defaults to: \fBFalse\fP .SS SYNTAX_ALIAS_OVERRIDES .sp This configuration key can be used to force highlight.js to use a certain logic on certain files based on their extensions. .sp It should be a dictionary containing the file extensions as keys and the highlighting language/category to use as values. .sp Defaults to: \fB{\(dq.spec\(dq: \(dqspecfile\(dq, \(dq.patch\(dq: \(dqdiff\(dq}\fP .SS ALLOW_API_UPDATE_GIT_TAGS .sp This configuration key determines whether users are allowed to update existing git tags via the API. When set to \fBFalse\fP, this essentially makes the API ignore whether the \fBforce\fP argument is set or not. .sp Default to: \fBTrue\fP .SS RepoSpanner Options .sp Pagure can be integrated with \fI\%repoSpanner\fP allowing to deploy pagure in a load\-balanced environment since the git repositories are then synced across multiple servers simultaneously. .sp Support for this integration has been included in Pagure version 5.0 and higher. .sp Here below are the different options one can/should use to integrate pagure with repoSpanner. .SS REPOBRIDGE_BINARY .sp This should contain the path to the repoBridge binary, which is used for pushing and pulling to/from repoSpanner. .sp Defaults to: \fB/usr/libexec/repobridge\fP\&. .SS REPOSPANNER_NEW_REPO .sp This configuration key instructs pagure to create new git repositories on repoSpanner or not. Its value should be the region in which the new git repositories should be created on. .sp Defaults to: \fBNone\fP\&. .SS REPOSPANNER_NEW_REPO_ADMIN_OVERRIDE .sp This configuration key can be used to let pagure admin override the default region used when creating new git repositories on repoSpanner. Its value should be a boolean. .sp Defaults to: \fBFalse\fP .SS REPOSPANNER_NEW_FORK .sp This configuration key instructs pagure on where/how to create new git repositories for the forks with repoSpanner. If \fBNone\fP, git repositories for forks are created outside of repoSpanner entirely. If \fBTrue\fP, git repositories for forks are created in the same region as the parent project. Otherwise, a region can be directly specified where git repositories for forks will be created. .sp Defaults to: \fBTrue\fP .SS REPOSPANNER_ADMIN_MIGRATION .sp This configuration key can be used to let admin manually migrate individual project into repoSpanner once it is set up. .sp Defaults to: \fBFalse\fP .SS REPOSPANNER_REGIONS .sp This configuration key can be used to specify the different region where repoSpanner is deployed and thus with which this pagure instance can be integrated. .sp An example entry could look like: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C REPOSPANNER_REGIONS = { \(aqdefault\(aq: {\(aqurl\(aq: \(aqhttps://nodea.regiona.repospanner.local:8444\(aq, \(aqrepo_prefix\(aq: \(aqpagure/\(aq, \(aqhook\(aq: None, \(aqca\(aq: \(aq/etc/pki/repospanner/pki/ca.crt\(aq, \(aqadmin_cert\(aq: {\(aqcert\(aq: \(aq/etc/pki/repospanner/pki/admin.crt\(aq, \(aqkey\(aq: \(aq/etc/pki/repospanner/pki/admin.key\(aq}, \(aqpush_cert\(aq: {\(aqcert\(aq: \(aq/etc/pki/repospanner/pki/pagure.crt\(aq, \(aqkey\(aq: \(aq/etc/pki/repospanner/pki/pagure.key\(aq}} } .ft P .fi .UNINDENT .UNINDENT .sp If this configuration key is not defined, pagure will consider that it is not set to be integrated with repoSpanner. .sp Defaults to: \fB{}\fP .SS SSH_KEYS_USERNAME_LOOKUP .sp This configuration key is used by the keyhelper script to indicate that the git username should be used and looked up. Use this if the username that is sent to ssh is specific for a unique Pagure user (i.e. not using a single \(dqgit@\(dq user for all git operations). .SS SSH_KEYS_USERNAME_FORBIDDEN .sp A list of usernames that are exempted from being verified via the keyhelper. .SS SSH_KEYS_USERNAME_EXPECT .sp This configuration key should contain the username that is used for git if a single SSH user is used for all git ssh traffic (i.e. \(dqgit\(dq). .SS SSH_KEYS_OPTIONS .sp This configuration key provides the options added to keys as they are returned to sshd, in the same format as AuthorizedKeysFile (see \(dqAUTHORIZED_KEYS FILE FORMAT\(dq in sshd(8)). .SS SSH_ADMIN_TOKEN .sp If not set to \fBNone\fP, \fBaclchecker\fP and \fBkeyhelper\fP will use this api admin token to get authorized to internal endpoints that they use. The token must have the \fBinternal_access\fP ACL. .sp 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\(aqs not possible to use the \fBIP_ALLOWED_INTERNAL\fP address list. .sp Defaults to: \fBNone\fP .SS SSH_COMMAND_REPOSPANNER .sp The command to run if a repository is on repospanner when aclchecker is in use. .SS SSH_COMMAND_NON_REPOSPANNER .sp The command to run if a repository is not on repospanner when aclchecker is in use. .SS MQTT Options .sp If approprietly configured pagure supports sending messages to an MQTT message queue. .sp Here below are the different configuration options to make it so. .SS MQTT_NOTIFICATIONS .sp Global configuration key to turn on or off the code to send notifications to an MQTT message queue. .sp Defaults to: \fBFalse\fP .SS MQTT_HOST .sp Host name of the MQTT server to send the MQTT notifications to. .sp Defaults to: \fBNone\fP .SS MQTT_PORT .sp Port of the MQTT server to use to send the MQTT notifications to. .sp Defaults to: \fBNone\fP .SS MQTT_USERNAME .sp Username to authenticate to the MQTT server as. .sp Defaults to: \fBNone\fP .SS MQTT_PASSWORD .sp Password to authenticate to the MQTT server with. .sp Defaults to: \fBNone\fP .SS MQTT_CA_CERTS .sp When using SSL\-based authentication to the MQTT server, use this configuration key to point to the CA cert to use. .sp Defaults to: \fBNone\fP .SS MQTT_CERTFILE .sp When using SSL\-based authentication to the MQTT server, use this configuration key to point to the cert file to use. .sp Defaults to: \fBNone\fP .SS MQTT_KEYFILE .sp When using SSL\-based authentication to the MQTT server, use this configuration key to point to the key file to use. .sp Defaults to: \fBNone\fP .SS MQTT_CERT_REQS .sp When using SSL\-based authentication to the MQTT server, use this configuration key to specify if the CERT is required. .sp Defaults to: \fBssl.CERT_REQUIRED\fP (from python\(aqs ssl library) .SS MQTT_TLS_VERSION .sp When using SSL\-based authentication to the MQTT server, use this configuration key to specify the TLS protocols to support/use. .sp Defaults to: \fBssl.PROTOCOL_TLSv1_2\fP (from python\(aqs ssl library) .SS MQTT_CIPHERS .sp When using SSL\-based authentication to the MQTT server, use this configuration key to specify the ciphers. .sp Defaults to: \fBNone\fP .SS MQTT_TOPIC_PREFIX .sp This configuration key can be used to specify a prefix to the mqtt messages sent. This prefix will be added to the topic used by pagure thus allowing the mqtt admins to specify a parent topic for all pagure\-related messages. .sp Defaults to: \fBNone\fP .SS ALWAYS_MQTT_ON_COMMITS .sp This configuration key can be used to enforce \fI\%mqtt\fP notifications on commits made on all projects in a pagure instance. .sp Defaults to: \fBFalse\fP\&. .SS PAGURE_PLUGINS_CONFIG .sp This option can be used to specify the configuration file used for loading plugins. It is not set by default, instead if must be declared explicitly. Also see the documentation on plugins at \fI\%Plugins\fP\&. .SS Deprecated configuration keys .SS FORK_FOLDER .sp This configuration key used to be use to specify the folder where the forks are placed. Since the release 2.0 of pagure, it has been deprecated, forks are now automatically placed in a sub\-folder of the folder containing the mains git repositories (ie \fBGIT_FOLDER\fP). .sp See the \fBUPGRADING.rst\fP file for more information about this change and how to handle it. .SS UPLOAD_FOLDER .sp This configuration key used to be use to specify where the uploaded releases are available. It has been replaced by \fIUPLOAD_FOLDER_PATH\fP in the release 2.10 of pagure. .SS GITOLITE_VERSION .sp This configuration key specifies which version of gitolite you are using, it can be either \fB2\fP or \fB3\fP\&. .sp Defaults to: \fB3\fP\&. .sp This has been replaced by \fIGITOLITE_BACKEND\fP in the release 3.0 of pagure. .SS DOCS_FOLDER, REQUESTS_FOLDER, TICKETS_FOLDER .sp These configuration values were removed. It has been found out that due to how Pagure writes repo names in the gitolite configuration file, these must have fixed paths relative to \fIGIT_FOLDER\fP\&. Specifically, they must occupy subdirectories \fIdocs\fP, \fIrequests\fP and \fItickets\fP under \fIGIT_FOLDER\fP\&. They are now computed automatically based on value of \fIGIT_FOLDER\fP\&. Usage of docs and tickets can be triggered by setting \fIENABLE_DOCS\fP and \fIENABLE_TICKETS\fP to \fITrue\fP (this is the default). .SS FILE_SIZE_HIGHLIGHT .sp This configuration key can be used to specify the maximum number of characters a file or diff should have to have syntax highlighting. Everything above this limit will not have syntax highlighting as this is a memory intensive procedure that easily leads to out of memory error on large files or diff. .sp Defaults to: \fB5000\fP .SS BOOTSTRAP_URLS_CSS .sp This configuration key can be used to specify the URL where are hosted the bootstrap CSS file since the files hosted on apps.fedoraproject.org used in pagure.io are not restricted in browser access. .sp Defaults to: \fB\(aqhttps://apps.fedoraproject.org/global/fedora\-bootstrap\-1.1.1/fedora\-bootstrap.css\(aq\fP .sp This has been deprecated by the new way of theming pagure, see the \fI\%theming documentation\fP .SS BOOTSTRAP_URLS_JS .sp This configuration key can be used to specify the URL where are hosted the bootstrap JS file since the files hosted on apps.fedoraproject.org used in pagure.io are not restricted in browser access. .sp Defaults to: \fB\(aqhttps://apps.fedoraproject.org/global/fedora\-bootstrap\-1.1.1/fedora\-bootstrap.js\(aq\fP .sp This has been deprecated by the new way of theming pagure, see the \fI\%theming documentation\fP .SS HTML_TITLE .sp This configuration key allows you to customize the HTML title of all the pages, from \fB\&... \- pagure\fP (default) to \fB\&... \- \fP\&. .sp Defaults to: \fBPagure\fP .sp This has been deprecated by the new way of theming pagure, see the \fI\%theming documentation\fP .SS GITOLITE_BACKEND .sp This configuration key allowed specifying the gitolite backend. This has now been replaced by GIT_AUTH_BACKEND, please see that option for information on valid values. .SS PAGURE_PLUGIN .sp This configuration key allows to specify the path to the plugins configuration file. It is set as an environment variable. It has been replaced by PAGURE_PLUGINS_CONFIG. The new variable does not modify the behavior of the old variable, however unlike PAGURE_PLUGIN it can be set in the main Pagure configuration. .SH PLUGINS .sp Pagure provides a mechanism for loading 3rd party plugins in the form of Flask Blueprints. The plugins are loaded from a separate configuration file that is specified using the PAGURE_PLUGINS_CONFIG option. There are at least two reasons for keeping plugins initialization outside the main pagure configuration file: .INDENT 0.0 .IP 1. 3 avoid circular dependencies errors. For example if the pagure configuration imports a plugin, which in turn imports the pagure configuration, the plugin could try to read a configuration option that has not been imported yet and thus raise an error .IP 2. 3 the pagure configuration is also loaded by other processes such as Celery workers. The Celery tasks might only be interested in reading the configuration settings without having to load any external plugin .UNINDENT .SS Loading the configuration .sp The configuration file can be loaded by setting the variable \fBPAGURE_PLUGINS_CONFIG\fP inside the pagure main configuration file, for example inside \fB/etc/pagure/pagure.cfg\fP\&. Alternatively, it is also possible to set the environment variable \fBPAGURE_PLUGINS_CONFIG\fP before starting the pagure server. If both variables are set, the environment variable takes precedence over the configuration file. .SS The configuration file .sp After Pagure has imported the configuration file defined in PAGURE_PLUGINS_CONFIG it will look for Flask Blueprints in a variable called \fBPLUGINS\fP defined in the same file, for example \fBPLUGINS = [ plugin1.blueprint, plugin2.blueprint, ... ]\fP\&. Pagure will then proceed to register any Blueprint into the main Flask app, in the same order as they are listed in \fBPLUGINS\fP\&. .sp An example configuration can be seen in \fBfiles/plugins.cfg.sample\fP inside the Pagure repository. .SH CUSTOMIZE THE GITOLITE CONFIGURATION .sp Pagure provides a mechanism to allow customizing the creation and compilation of the configuration file of gitolite. .sp To customize the gitolite configuration file, we invite you to look at the \fI\%sources of the module pagure.lib.git_auth\fP\&. .sp As you can see it defines the following class: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C class GitAuthHelper(object): __metaclass__ = abc.ABCMeta @staticmethod @abc.abstractmethod def generate_acls(): pass @classmethod @abc.abstractmethod def remove_acls(self, session, project): pass .ft P .fi .UNINDENT .UNINDENT .sp This will be the class you will have to inherit from in order to inject your own code. You will then declare an entry point in your \fIsetup.py\fP following this template: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C entry_points=\(dq\(dq\(dq [pagure.git_auth.helpers] my_git_auth = my_pagure.my_module:MyGitAuthTestHelper \(dq\(dq\(dq .ft P .fi .UNINDENT .UNINDENT .sp Then you can adjust pagure\(aqs configuration file to say: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C GITOLITE_BACKEND = \(aqmy_git_auth\(aq .ft P .fi .UNINDENT .UNINDENT .SH DEVELOPMENT .SS Get the sources .sp Anonymous: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C git clone https://pagure.io/pagure.git .ft P .fi .UNINDENT .UNINDENT .sp Contributors: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C git clone ssh://git@pagure.io/pagure.git .ft P .fi .UNINDENT .UNINDENT .SS Dependencies .sp Install the build dependencies of pagure: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C sudo dnf install git python\-virtualenv libgit2\-devel \e libjpeg\-devel gcc libffi\-devel redhat\-rpm\-config .ft P .fi .UNINDENT .UNINDENT .sp The python dependencies of pagure are listed in the file \fBrequirements.txt\fP at the top level of the sources. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C virtualenv pagure_env source ./pagure_env/bin/activate pip install pygit2==.* # e.g. 0.23.* pip install \-r requirements.txt .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 working in a \fI\%virtualenv\fP is tricky due to the dependency on \fI\%pygit2\fP and thus on \fI\%libgit2\fP but the pygit2 \fI\%documentation has a solution for this\fP\&. .UNINDENT .UNINDENT .SS How to run pagure .sp There are several options when it comes to a development environment. Vagrant will provide you with a virtual machine which you can develop on, you can use a container to run pagure or you can install it directly on your host machine. The README has detailed instructions for the different options. .SS Run pagure for development .sp Adjust the configuration file (secret key, database URL, admin group...) See \fI\%Configuration\fP for more detailed information about the configuration. .sp Create the database scheme: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C \&./createdb.py .ft P .fi .UNINDENT .UNINDENT .sp Create the folder that will receive the different git repositories: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C mkdir {repos,docs,forks,tickets,requests,remotes} .ft P .fi .UNINDENT .UNINDENT .sp Run the server: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C \&./runserver.py .ft P .fi .UNINDENT .UNINDENT .sp If you want to change some configuration key you can create a file, place the configuration change in it and use it with .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C \&./runserver.py \-c .ft P .fi .UNINDENT .UNINDENT .sp For example, create the file \fBconfig\fP with in it: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C from datetime import timedelta # Makes the admin session longer ADMIN_SESSION_LIFETIME = timedelta(minutes=20000000) # Use a postgresql database instead of sqlite DB_URL = \(aqpostgresql://user:pass@localhost/pagure\(aq # Change the OpenID endpoint FAS_OPENID_ENDPOINT = \(aqhttps://id.stg.fedoraproject.org\(aq APP_URL = \(aq*\(aq EVENTSOURCE_SOURCE = \(aqhttp://localhost:8080\(aq EVENTSOURCE_PORT = \(aq8080\(aq DOC_APP_URL = \(aq*\(aq # Avoid sending email when developing EMAIL_SEND = False .ft P .fi .UNINDENT .UNINDENT .sp and run the server with: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C \&./runserver.py \-c config .ft P .fi .UNINDENT .UNINDENT .sp To get some profiling information you can also run it as: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C \&./runserver.py \-\-profile .ft P .fi .UNINDENT .UNINDENT .sp You should be able to access the server at \fI\%http://localhost:5000\fP .sp Every time you save a file, the project will be automatically restarted so you can see your change immediately. .SS Create a pull\-request for testing .sp When working on pagure, it is pretty often that one wanted to work on a feature or a bug related to pull\-requests needs to create one. .sp Making a pull\-request for development purposes isn\(aqt hard, if you remember that since you\(aqre running a local instance, the git repos created in your pagure instance are also local. .sp So here are in a few steps that one could perform to create a pull\-request in a local pagure instance. .INDENT 0.0 .IP \(bu 2 Create a project on your pagure instance, let\(aqs say it will be called \fBtest\fP .IP \(bu 2 Create a folder \fBclones\fP somewhere in your system (you probably do not want it in the \fBrepos\fP folder created above, next to it is fine though): .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C mkdir clones .ft P .fi .UNINDENT .UNINDENT .IP \(bu 2 Clone the repo of the \fBtest\fP project into this \fBclones\fP folder and move into it: .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C cd clones git clone ~/path/to/pagure/repos/test.git cd test .ft P .fi .UNINDENT .UNINDENT .IP \(bu 2 Add and commit some files: .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C echo \(dq*~\(dq > .gitignore git add .gitignore git commit \-m \(dqAdd a .gitignore file\(dq echo \(dqBSD\(dq > LICENSE git add LICENSE git commit \-m \(dqAdd a LICENSE file\(dq .ft P .fi .UNINDENT .UNINDENT .IP \(bu 2 Push these changes: .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C git push \-u origin master .ft P .fi .UNINDENT .UNINDENT .IP \(bu 2 Create a new branch and add a commit in it: .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C git branch new_branch git checkout new_branch touch test git add test git commit \-m \(dqAdd file: test\(dq .ft P .fi .UNINDENT .UNINDENT .IP \(bu 2 Push this new branch: .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C git push \-u origin new_branch .ft P .fi .UNINDENT .UNINDENT .UNINDENT .sp Then go back to your pagure instance running in your web\-browser, check the \fBtest\fP project. You should see two branches: \fBmaster\fP and \fBnew_branch\fP\&. From there you should be able to open a new pull\-request, either from the front page or via the \fBFile Pull Request\fP button in the \fBPull Requests\fP page. .SS Coding standards .sp We are trying to make the code \fI\%PEP8\-compliant\fP\&. There is a \fI\%flake8 tool\fP that can automatically check your source. .sp We run the source code through \fI\%black\fP as part of the tests, so you may have to do some adjustments or run it yourself (which is simple: \fBblack /path/to/pagure\fP). .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 flake8 and black are available in Fedora: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C dnf install python3\-flake8 python3\-black .ft P .fi .UNINDENT .UNINDENT .sp or .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C yum install python3\-flake8 python3\-black .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .SS Send patch .sp The easiest way to work on pagure is to make your own branch in git, make your changes to this branch, commit whenever you want, rebase on master, whenever you need and when you are done, send the patch either by email, via the trac or a pull\-request (using git or github). .sp The workflow would therefore be something like: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C git branch git checkout git commit file1 file2 git commit file3 file4 git checkout master git pull git checkout git rebase master git format\-patch \-2 .ft P .fi .UNINDENT .UNINDENT .sp 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 \fBgit format\-patch \-2\fP is not needed. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Though not required, it’s a good idea to begin the commit message with a single short (less than 50 character) line summarizing the change, followed by a blank line and then a more thorough description. The text up to the first blank line in a commit message is treated as the commit title, and that title is used throughout Git. For example, git\-format\-patch turns a commit into email, and it uses the title on the Subject line and the rest of the commit in the body. Pagure uses lines that contain only \(aqFixes #number\(aq as references to issues. If for example a commit message of a pagure patch has a line \(aqFixes #3547\(aq and a pullrequest (PR) gets created in pagure, this PR will be linked to from \fBhttps://pagure.io/pagure/issue/3547\fP .UNINDENT .UNINDENT .SS Unit\-tests .sp Pagure has a number of unit\-tests. .sp 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. .sp Tests checking that function are failing when/how we want are as important as tests checking they work the way they are intended to. .sp So here are a few steps that one could perform to run unit\-tests in a local pagure instance. .INDENT 0.0 .IP \(bu 2 Install the dependencies: .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C pip install \-r requirements\-testing.txt .ft P .fi .UNINDENT .UNINDENT .IP \(bu 2 Run it: .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C tox ./test/ .ft P .fi .UNINDENT .UNINDENT .UNINDENT .sp If you want to run a single interpreter, cou can use: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C tox \-e py38 ./test/ .ft P .fi .UNINDENT .UNINDENT .sp Each unit\-tests files (located under \fBtests/\fP) can be called by alone, allowing easier debugging of the tests. For example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C pytest\-3 tests/test_pagure_lib.py .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 In order to have coverage information you might have to install \fBpython\-coverage\fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C dnf install python3\-pytest\-cov .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp To run the unit\-tests, there is also a container available with all the dependencies needed. Use the following command to run the tests .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ ./dev/run\-tests\-container.py .ft P .fi .UNINDENT .UNINDENT .sp 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. .SH CONTRIBUTING .sp If you\(aqre submitting patches to pagure, please observe the following: .INDENT 0.0 .IP \(bu 2 Check that your python code is \fI\%PEP8\-compliant\fP\&. There is a \fI\%flake8 tool\fP that automatically checks the sources as part of the tests. .IP \(bu 2 We run the source code through \fI\%black\fP as part of the tests, so you may have to do some adjustments or run it yourself (which is simple: \fBblack /path/to/pagure\fP). .IP \(bu 2 Check that your code doesn\(aqt break the test suite. The test suite can be run using \fBtox\fP at the top of the sources, you mayuse \fBtox \-e py38 ./test/\fP to run a single version of python. You can also run a single file by calling pytest directly: \fBpytest\-3 tests/test_style.py\fP\&. See \fI\%Development\fP for more information about the test suite. .IP \(bu 2 If you are adding new code, please write tests for them in \fBtests/\fP, \fBtox .\fP will run the tests and show you the coverage of the code by the unit\-tests. .IP \(bu 2 If your change warrants a modification to the docs in \fBdoc/\fP or any docstrings in \fBpagure/\fP please make that modification. .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 You have a doubt, you don\(aqt know how to do something, you have an idea but don\(aqt know how to implement it, you just have something bugging you? .sp Come to see us on IRC: \fB#pagure\fP or \fB#fedora\-apps\fP on irc.freenode.net or directly on \fI\%the project\fP\&. .UNINDENT .UNINDENT .SH CONTRIBUTORS TO PAGURE .sp Pagure would be nothing without its contributors. .sp On May 14, 2019 (release 5.10.0) the list looks as follow: .TS center; |l|l|. _ T{ Number of commits T} T{ Contributor T} _ T{ 6799 T} T{ Pierre\-Yves Chibon <\fI\%pingou@pingoured.fr\fP> T} _ T{ 328 T} T{ Ryan Lerch <\fI\%rlerch@redhat.com\fP> T} _ T{ 172 T} T{ Vivek Anand <\fI\%vivekanand1101@gmail.com\fP> T} _ T{ 144 T} T{ Julen Landa Alustiza <\fI\%jlanda@fedoraproject.org\fP> T} _ T{ 139 T} T{ farhaanbukhsh <\fI\%farhaan.bukhsh@gmail.com\fP> T} _ T{ 134 T} T{ Clement Verna <\fI\%cverna@tutanota.com\fP> T} _ T{ 133 T} T{ Patrick Uiterwijk <\fI\%puiterwijk@redhat.com\fP> T} _ T{ 98 T} T{ Patrick Uiterwijk <\fI\%patrick@puiterwijk.org\fP> T} _ T{ 88 T} T{ Farhaan Bukhsh <\fI\%farhaan.bukhsh@gmail.com\fP> T} _ T{ 64 T} T{ Slavek Kabrda <\fI\%bkabrda@redhat.com\fP> T} _ T{ 59 T} T{ Johan Cwiklinski <\fI\%johan@x\-tnd.be\fP> T} _ T{ 52 T} T{ Karsten Hopp <\fI\%karsten@redhat.com\fP> T} _ T{ 47 T} T{ Mark Reynolds <\fI\%mreynolds@redhat.com\fP> T} _ T{ 36 T} T{ Neal Gompa <\fI\%ngompa13@gmail.com\fP> T} _ T{ 33 T} T{ Lubomír Sedlář <\fI\%lsedlar@redhat.com\fP> T} _ T{ 32 T} T{ Matt Prahl <\fI\%mprahl@redhat.com\fP> T} _ T{ 32 T} T{ Pradeep CE (cep) <\fI\%breathingcode@gmail.com\fP> T} _ T{ 25 T} T{ Lubomír Sedlář <\fI\%lubomir.sedlar@gmail.com\fP> T} _ T{ 23 T} T{ rahul Bajaj <\fI\%you@example.com\fP> T} _ T{ 20 T} T{ Jeremy Cline <\fI\%jeremy@jcline.org\fP> T} _ T{ 19 T} T{ Aurélien Bompard <\fI\%aurelien@bompard.org\fP> T} _ T{ 19 T} T{ Fabien Boucher <\fI\%fboucher@redhat.com\fP> T} _ T{ 19 T} T{ Gaurav Kumar <\fI\%aavrug@gmail.com\fP> T} _ T{ 19 T} T{ Lenka Segura <\fI\%lenka@sepu.cz\fP> T} _ T{ 18 T} T{ Abhijeet Kasurde <\fI\%akasurde@redhat.com\fP> T} _ T{ 18 T} T{ Sayan Chowdhury <\fI\%sayan.chowdhury2012@gmail.com\fP> T} _ T{ 17 T} T{ Adam Williamson <\fI\%awilliam@redhat.com\fP> T} _ T{ 17 T} T{ Brian Stinson <\fI\%brian@bstinson.com\fP> T} _ T{ 17 T} T{ Ralph Bean <\fI\%rbean@redhat.com\fP> T} _ T{ 15 T} T{ Igor Gnatenko <\fI\%ignatenkobrain@fedoraproject.org\fP> T} _ T{ 15 T} T{ Vibhor Verma <\fI\%vibhcool@gmail.com\fP> T} _ T{ 14 T} T{ Justin W. Flory <\fI\%git@jwf.io\fP> T} _ T{ 13 T} T{ Ghost\-script <\fI\%subho.prp@gmail.com\fP> T} _ T{ 13 T} T{ Martin Basti <\fI\%mbasti@redhat.com\fP> T} _ T{ 13 T} T{ Mathieu Bridon <\fI\%bochecha@fedoraproject.org\fP> T} _ T{ 11 T} T{ Shengjing Zhu <\fI\%zsj950618@gmail.com\fP> T} _ T{ 9 T} T{ Michael Watters <\fI\%michael.watters@dart.biz\fP> T} _ T{ 9 T} T{ mprahl <\fI\%mprahl@redhat.com\fP> T} _ T{ 8 T} T{ Lei Yang <\fI\%yltt1234512@gmail.com\fP> T} _ T{ 8 T} T{ Paul W. Frields <\fI\%stickster@gmail.com\fP> T} _ T{ 7 T} T{ René Genz <\fI\%liebundartig@freenet.de\fP> T} _ T{ 7 T} T{ Sergio Durigan Junior <\fI\%sergiodj@sergiodj.net\fP> T} _ T{ 7 T} T{ zPlus <\fI\%zplus@peers.community\fP> T} _ T{ 6 T} T{ Michael Scherer <\fI\%misc@redhat.com\fP> T} _ T{ 6 T} T{ ymdatta <\fI\%ymdatta@protonmail.com\fP> T} _ T{ 5 T} T{ Fabio Valentini <\fI\%decathorpe@gmail.com\fP> T} _ T{ 5 T} T{ Lukas Holecek <\fI\%hluk@email.cz\fP> T} _ T{ 5 T} T{ Mike McLean <\fI\%mikem@redhat.com\fP> T} _ T{ 5 T} T{ Oliver Gutierrez <\fI\%ogutierrez@redhat.com\fP> T} _ T{ 5 T} T{ Shaily <\fI\%shaily15297@yahoo.com\fP> T} _ T{ 5 T} T{ Till Maas <\fI\%opensource@till.name\fP> T} _ T{ 5 T} T{ jingjing <\fI\%sanri.ok@163.com\fP> T} _ T{ 5 T} T{ vanzhiganov <\fI\%vanzhiganov@ya.ru\fP> T} _ T{ 5 T} T{ yangl1996 <\fI\%yltt1234512@gmail.com\fP> T} _ T{ 4 T} T{ Alex Gleason <\fI\%alex@alexgleason.me\fP> T} _ T{ 4 T} T{ Eric Barbour <\fI\%ebarbour@redhat.com\fP> T} _ T{ 4 T} T{ Maciej Lasyk <\fI\%maciek@lasyk.info\fP> T} _ T{ 4 T} T{ clime <\fI\%clime@redhat.com\fP> T} _ T{ 3 T} T{ Akanksha <\fI\%akanksha_mishra01@yahoo.com\fP> T} _ T{ 3 T} T{ Andrew Engelbrecht <\fI\%andrew@engelbrecht.io\fP> T} _ T{ 3 T} T{ Ankush Behl <\fI\%cloudbehl@gmail.com\fP> T} _ T{ 3 T} T{ Anthony Lackey <\fI\%alackey96@gmail.com\fP> T} _ T{ 3 T} T{ Chenxiong Qi <\fI\%cqi@redhat.com\fP> T} _ T{ 3 T} T{ Dhriti Shikhar <\fI\%dhriti.shikhar.rokz@gmail.com\fP> T} _ T{ 3 T} T{ Eric Barbour <\fI\%emb4gu@virginia.edu\fP> T} _ T{ 3 T} T{ FeRD (Frank Dana) <\fI\%ferdnyc@gmail.com\fP> T} _ T{ 3 T} T{ Jan Pokorný <\fI\%jpokorny@redhat.com\fP> T} _ T{ 3 T} T{ Jason Tibbitts <\fI\%tibbs@math.uh.edu\fP> T} _ T{ 3 T} T{ Kushal Khandelwal <\fI\%kushal124@gmail.com\fP> T} _ T{ 3 T} T{ Michal Konečný <\fI\%mkonecny@redhat.com\fP> T} _ T{ 3 T} T{ Miro Hrončok <\fI\%miro@hroncok.cz\fP> T} _ T{ 3 T} T{ Pedro Lima <\fI\%pedro.lima@gmail.com\fP> T} _ T{ 3 T} T{ Pierre\-YvesChibon <\fI\%pingou@fedoraproject.org\fP> T} _ T{ 3 T} T{ Ricky Elrod <\fI\%ricky@elrod.me\fP> T} _ T{ 3 T} T{ Ryan Lerch <\fI\%rlerch@localhost.localdomain\fP> T} _ T{ 3 T} T{ Stefan Bühler <\fI\%stbuehler@web.de\fP> T} _ T{ 3 T} T{ bill auger <\fI\%mr.j.spam.me@gmail.com\fP> T} _ T{ 3 T} T{ cep <\fI\%breathingcode@gmail.com\fP> T} _ T{ 3 T} T{ shivani <\fI\%smshivani579@gmail.com\fP> T} _ T{ 3 T} T{ skrzepto <\fI\%shims506@gmail.com\fP> T} _ T{ 3 T} T{ tenstormavi <\fI\%avi.avinash3008@gmail.com\fP> T} _ T{ 2 T} T{ Akshay Gaikwad <\fI\%akgaikwad001@gmail.com\fP> T} _ T{ 2 T} T{ Anatoli Babenia <\fI\%anatoli@rainforce.org\fP> T} _ T{ 2 T} T{ Björn Persson T} _ T{ 2 T} T{ Carlos Mogas da Silva <\fI\%r3pek@r3pek.org\fP> T} _ T{ 2 T} T{ Daniel Mach <\fI\%dmach@redhat.com\fP> T} _ T{ 2 T} T{ Fabian Arrotin <\fI\%fabian.arrotin@arrfab.net\fP> T} _ T{ 2 T} T{ Hervé Beraud <\fI\%hberaud@redhat.com\fP> T} _ T{ 2 T} T{ Kamil Páral <\fI\%kparal@redhat.com\fP> T} _ T{ 2 T} T{ Luis Guzman <\fI\%ark@switnet.org\fP> T} _ T{ 2 T} T{ MR <\fI\%mrx@mailinator.com\fP> T} _ T{ 2 T} T{ Neha Kandpal <\fI\%iec2015048@iiita.ac.in\fP> T} _ T{ 2 T} T{ Nuno Maltez <\fI\%nuno@cognitiva.com\fP> T} _ T{ 2 T} T{ Ompragash <\fI\%om.apsara@gmail.com\fP> T} _ T{ 2 T} T{ Peter Oliver <\fI\%git@mavit.org.uk\fP> T} _ T{ 2 T} T{ Rahul Bajaj <\fI\%rahulrb0509@gmail.com\fP> T} _ T{ 2 T} T{ Richard Marko <\fI\%rmarko@fedoraproject.org\fP> T} _ T{ 2 T} T{ Simo Sorce <\fI\%simo@redhat.com\fP> T} _ T{ 2 T} T{ Stasiek Michalski <\fI\%hellcp@opensuse.org\fP> T} _ T{ 2 T} T{ Tim Flink <\fI\%tflink@fedoraproject.org\fP> T} _ T{ 2 T} T{ Tim Landscheidt <\fI\%tim@tim\-landscheidt.de\fP> T} _ T{ 2 T} T{ Todd Zullinger <\fI\%tmz@pobox.com\fP> T} _ T{ 2 T} T{ William Moreno Reyes <\fI\%williamjmorenor@gmail.com\fP> T} _ T{ 2 T} T{ Your Name <\fI\%jlanda@fedoraproject.org\fP> T} _ T{ 2 T} T{ bruno <\fI\%bruno@wolff.to\fP> T} _ T{ 2 T} T{ dhrish20 <\fI\%dhrish20@gmail.com\fP> T} _ T{ 2 T} T{ hellcp <\fI\%hellcp@opensuse.org\fP> T} _ T{ 2 T} T{ yadneshk <\fI\%yadnesh45@gmail.com\fP> T} _ T{ 2 T} T{ “AnjaliPardeshi” <“\fI\%anjalipardeshi92@gmail.com\fP”> T} _ T{ 1 T} T{ Akanksha Mishra <\fI\%akanksha_mishra01@yahoo.com\fP> T} _ T{ 1 T} T{ Aleksandra Fedorova (bookwar) <\fI\%afedorova@mirantis.com\fP> T} _ T{ 1 T} T{ Alexander Scheel <\fI\%ascheel@redhat.com\fP> T} _ T{ 1 T} T{ Alois Mahdal <\fI\%amahdal@redhat.com\fP> T} _ T{ 1 T} T{ Amol Kahat <\fI\%akahat@redhat.com\fP> T} _ T{ 1 T} T{ Anthony Lackey <\fI\%alackey@localhost.localdomain\fP> T} _ T{ 1 T} T{ Antoni Segura Puimedon <\fI\%celebdor@gmail.com\fP> T} _ T{ 1 T} T{ Arti Laddha <\fI\%artiladdha53@gmail.com\fP> T} _ T{ 1 T} T{ Brian (bex) Exelbierd <\fI\%bex@pobox.com\fP> T} _ T{ 1 T} T{ Carl George <\fI\%carl@george.computer\fP> T} _ T{ 1 T} T{ Charelle Collett <\fI\%ccollett@redhat.com\fP> T} _ T{ 1 T} T{ David Caro <\fI\%dcaroest@redhat.com\fP> T} _ T{ 1 T} T{ Devesh Kumar Singh <\fI\%deveshkusingh@gmail.com\fP> T} _ T{ 1 T} T{ Eashan <\fI\%eashankadam@gmail.com\fP> T} _ T{ 1 T} T{ Felix Yan <\fI\%felixonmars@users.sf.net\fP> T} _ T{ 1 T} T{ Filip Valder <\fI\%fvalder@redhat.com\fP> T} _ T{ 1 T} T{ Frank Dana (FeRD) <\fI\%ferdnyc@gmail.com\fP> T} _ T{ 1 T} T{ Haikel Guemar <\fI\%hguemar@fedoraproject.org\fP> T} _ T{ 1 T} T{ Hazel Smith <\fI\%hazel@hazelesque.uk\fP> T} _ T{ 1 T} T{ Jeremy Cline <\fI\%jcline@redhat.com\fP> T} _ T{ 1 T} T{ Jingjing Shao <\fI\%sanri.ok@163.com\fP> T} _ T{ 1 T} T{ John Florian <\fI\%jflorian@doubledog.org\fP> T} _ T{ 1 T} T{ Jun Aruga <\fI\%jaruga@redhat.com\fP> T} _ T{ 1 T} T{ Ken Dreyer <\fI\%kdreyer@redhat.com\fP> T} _ T{ 1 T} T{ Kunaal Jain <\fI\%kunaalus@gmail.com\fP> T} _ T{ 1 T} T{ Mary Kate Fain <\fI\%mk@marykatefain.com\fP> T} _ T{ 1 T} T{ Mathew Robinson <\fI\%mathew.robinson3114@gmail.com\fP> T} _ T{ 1 T} T{ Michal Srb <\fI\%michal@redhat.com\fP> T} _ T{ 1 T} T{ Mohan Boddu <\fI\%mboddu@redhat.com\fP> T} _ T{ 1 T} T{ Nils Philippsen <\fI\%nils@redhat.com\fP> T} _ T{ 1 T} T{ Pavel Raiskup <\fI\%praiskup@redhat.com\fP> T} _ T{ 1 T} T{ Peter Kolínek <\fI\%fedora@pessoft.com\fP> T} _ T{ 1 T} T{ Petr Šplíchal <\fI\%psplicha@redhat.com\fP> T} _ T{ 1 T} T{ Randy Barlow <\fI\%randy@electronsweatshop.com\fP> T} _ T{ 1 T} T{ Robert Bost <\fI\%rbost@redhat.com\fP> T} _ T{ 1 T} T{ Romain DEP. <\fI\%rom1dep@gmail.com\fP> T} _ T{ 1 T} T{ Ryan Lerch <\fI\%ryanlerch@gmail.com\fP> T} _ T{ 1 T} T{ Sachin Kamath <\fI\%sskamath96@gmail.com\fP> T} _ T{ 1 T} T{ Snehal Karale <\fI\%skarale@redhat.com\fP> T} _ T{ 1 T} T{ Stanislav Laznicka <\fI\%slaznick@redhat.com\fP> T} _ T{ 1 T} T{ Stanislav Ochotnicky <\fI\%sochotnicky@redhat.com\fP> T} _ T{ 1 T} T{ Stephen Gallagher <\fI\%sgallagh@redhat.com\fP> T} _ T{ 1 T} T{ Tiago M. Vieira <\fI\%tiago@tvieira.com\fP> T} _ T{ 1 T} T{ Till Hofmann <\fI\%hofmann@kbsg.rwth\-aachen.de\fP> T} _ T{ 1 T} T{ Vadim Rutkovsky <\fI\%vrutkovs@redhat.com\fP> T} _ T{ 1 T} T{ Vyacheslav Anzhiganov <\fI\%vanzhiganov@ya.ru\fP> T} _ T{ 1 T} T{ Yves Martin <\fI\%ymartin1040@gmail.com\fP> T} _ T{ 1 T} T{ abhishek <\fI\%abhishekarora12@gmail.com\fP> T} _ T{ 1 T} T{ abhishek goswami <\fI\%abhishekg785@gmail.com\fP> T} _ T{ 1 T} T{ alunux <\fI\%fadlun.net@gmail.com\fP> T} _ T{ 1 T} T{ anar <\fI\%anaradilovab@gmail.com\fP> T} _ T{ 1 T} T{ anatoly techtonik <\fI\%techtonik@gmail.com\fP> T} _ T{ 1 T} T{ anshukira <\fI\%aks.anshu03@gmail.com\fP> T} _ T{ 1 T} T{ chocos10 <\fI\%iec2015048@iiita.ac.in\fP> T} _ T{ 1 T} T{ d3prof3t <\fI\%saurabhpysharma@gmail.com\fP> T} _ T{ 1 T} T{ ishcherb <\fI\%ishcherb@redhat.com\fP> T} _ T{ 1 T} T{ jcvicelli <\fI\%jcvicelli@gmail.com\fP> T} _ T{ 1 T} T{ josef radinger <\fI\%cheese@nosuchhost.net\fP> T} _ T{ 1 T} T{ midipix <\fI\%writeonce@midipix.org\fP> T} _ T{ 1 T} T{ \fI\%mrx@mailinator.com\fP <\fI\%mrx@mailinator.com\fP> T} _ T{ 1 T} T{ pingou <\fI\%pingou@fedoraproject.org\fP> T} _ T{ 1 T} T{ prasad0896 <\fI\%shendep@yahoo.co.in\fP> T} _ T{ 1 T} T{ rishika7000 <\fI\%rishika7000@gmail.com\fP> T} _ T{ 1 T} T{ ryanlerch <\fI\%rlerch@redhat.com\fP> T} _ T{ 1 T} T{ sclark <\fI\%simon.richard.clark@gmail.com\fP> T} _ T{ 1 T} T{ skrzepto <\fI\%skrzepto@gmail.com\fP> T} _ T{ 1 T} T{ smit thakkar <\fI\%smitthakkar96@gmail.com\fP> T} _ T{ 1 T} T{ smurfix <\fI\%matthias@urlichs.de\fP> T} _ T{ 1 T} T{ vibhcool <\fI\%vibhcool@gmail.com\fP> T} _ T{ 1 T} T{ vivekanand1101 <\fI\%vivekanand1101@gmail.com\fP> T} _ T{ 1 T} T{ waifu <\fI\%heweyo6819@ualmail.com\fP> T} _ .TE .sp This list is generated using .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C git shortlog \-s \-n \-e .ft P .fi .UNINDENT .UNINDENT .sp The old pagure logo has been created by \fBMicah Denn \fP, the new one, as well as the entire version 2 of the user interface (using bootstrap) is the work of \fBRyan Lerch \fP many thanks to them for their work and understanding during the process. .SH RUNS HERE .SS List of locations where Pagure is currently used .sp Please add yourself here if you run a local version of Pagure. Please also describe what you are using it for. .TS center; |l|l|l|l|. _ T{ # T} T{ Project T} T{ Site Name T} T{ Used for T} _ T{ 0 T} T{ \fI\%Fedora\fP T} T{ \fI\%https://src.fedoraproject.org\fP T} T{ Development of Fedora Linux distribution T} _ T{ 1 T} T{ \fI\%CentOS\fP T} T{ \fI\%https://git.centos.org\fP T} T{ Development of CentOS Linux distribution T} _ T{ 2 T} T{ \fI\%Midipix\fP T} T{ \fI\%https://dev.midipix.org\fP T} T{ Development of Midipix and related projects T} _ T{ 3 T} T{ \fI\%Cool Bug\fP T} T{ \fI\%https://repo.coolbug.org\fP T} T{ Development of personal projects T} _ .TE .sp This documentation is generated from the \fBdoc\fP folder in the \fI\%pagure\(aqs sources\fP\&. Feel free to report issues about the documentation on the \fI\%pagure issue tracker\fP or even better, contribute to it! .INDENT 0.0 .IP \(bu 2 \fI\%Index\fP .IP \(bu 2 \fI\%Module Index\fP .IP \(bu 2 \fI\%Search Page\fP .UNINDENT .SH AUTHOR Pierre-Yves Chibon .SH COPYRIGHT 2023, Red Hat Inc, Pierre-Yves Chibon .\" Generated by docutils manpage writer. .