Most of today's developers publish their source code on GitHub, BitBucket or on their own GitLab instance. These tools typically also provide a way to release new versions based on Git tags or by uploading custom archives.
Advanced users and developers typically prefer to download the app directly from these services whereas administrators or novice users look for app releases on the App Store. This means that you have to take care of publishing two releases on two different platforms.
We want to avoid duplication and make it harder to ship broken releases by mistake, therefore we went for the following solution:
* Your app's source code is hosted on GitHub or a similar service
* You should use Git tags to create new releases on these services
* Archives are typically created automatically for you. If you require compilation or other transformations like minification, you should upload a pre-built archive to the appropriate releases page
This keeps your repository up to date and satisfies the needs of developers and advanced users.
Hosting the archive on a different host means of course that we can not guarantee that the contents have not been tampered with. Neither can we guarantee that the actual app developer uploaded the app. Therefore we require you to sign your app using a certificate.
Then post the contents of your **APP_ID.csr** (e.g. **~/.nextcloud/certificates/news.csr**) on `on our certificate repository <https://github.com/nextcloud/app-certificate-requests>`_ as pull request and configure your GitHub account to show your mail address in your profile.
We might ask you for further information to verify that you're the legitimate owner of the application. Make sure to keep the private key file (**APP_ID.key**, e.g. **~/.nextcloud/certificates/news.key**) secret and not disclose it to any third-parties.
After we approved your certificate, we will post your signed public certificate (APP_ID.crt) as a response in your app's directory. Take the contents and store it in the same folder with the file name **APP_ID.crt** (e.g. **~/.nextcloud/certificates/news.crt**). Make sure to get rid of excess whitespace at the beginning and end of your file. Your public signed certificate's file contents should look similar to this::
..note:: Be sure to follow the directory and naming structure for certificates. All our documentation examples and tools will assert this structure.
Registering an App
~~~~~~~~~~~~~~~~~~
After you've obtained your signed public certificate you can use it to register your app id on the App Store. To do that either use the :ref:`REST API <api-register-app>` or use the App Store's `register app web interface <https://apps.nextcloud.com/app/register>`_.
The interface will ask you for the following things:
***Certificate**: Paste in the contents of your public certificate, e.g. **~/.nextcloud/certificates/news.crt**
***Signature**: A signature over your app id to verify that you own the private certificate. Can be calculated by using the following command::
We will then verify the certificate and signature and register you as the app's owner. You are now able to publish releases.
Uploading an App Release
~~~~~~~~~~~~~~~~~~~~~~~~
After you've registered your app you can upload your app's releases to the App Store. To do that either use the :ref:`REST API <api-create-release>` or use the App Store's `upload app release web interface <https://apps.nextcloud.com/app/upload>`_.
The interface will ask you for the following things:
***Download**: A download link to your app release archive (tar.gz)
***Nightly**: Check if you are uploading a nightly release
***Signature**: A signature over your release archive. Can be calculated by using the following command::
We then download the archive and verify the signature. In addition we try to verify and use as much information as possible form the archive, e.g.:
* The archive most only contain one top level folder consisting of lower case ASCII characters and underscores
* The archive must contain an **info.xml** file inside the **appinfo** directory which in turn is located in the top folder
* The info.xml is reformatted using XSLT to bring everything into the correct order (required for XSD 1.0) and unknown elements are dropped. Old elements are migrated to their new equivalents if possible. Afterwards we validate it using an XML Schema (see :ref:`info-schema`)
If everything went well the release is then either created or updated. The downloaded archive will be deleted from our server.
Revoking a Certificate
~~~~~~~~~~~~~~~~~~~~~~
If you've lost or leaked your private certificate you want to revoke your certificate.
You can revoke your previous certificate by either posting your public certificate and revocation request `on our issue tracker <https://github.com/nextcloud/appstore/issues/new>`_ or by requesting a new certificate for an already requested app id.
After you've obtained a new certificate, simply use it to register your app id again (only owners are allowed to do this). This will delete all previous releases from our server since their signature has become invalid.
<description lang="de">< umgehen kann]]></description>
* if you do not have an id yet, create an app on the apps.owncloud.com app store and use that id. This ensures that the id is unique and unused. You can delete the app afterwards if you do not want to publish your app on both stores.
..note:: The regex for matching the line is **^## (\\d+\\.\\d+\\.\\d+)**, the regex for nightlies is **^## [Unreleased]**
The version has to be equal to the version in your info.xml. If the parser can't find a changelog entry, it will be set to an empty string. Only the changelog for the current release will be imported.
The changelog for nightlies will be taken from the **## [Unreleased]** block
We provide an XML schema for the info.xml file which is available under `https://apps.nextcloud.com/schema/apps/info.xsd <https://apps.nextcloud.com/schema/apps/info.xsd>`_ and can be used to validate your info.xml or provide autocompletion in your IDE.
You can validate your info.xml using `various online tools <http://www.utilities-online.info/xsdvalidation/>`_
Various IDEs automatically validate and auto complete XML elements and attributes if you add the schema in your info.xml like this:
