Metadata-Version: 1.1
Name: githubbuildout
Version: 0.2
Summary: Buildout extension to enable downloads from private GitHub repositories into buildout find-links and download recipes
Home-page: https://github.com/isolationism/githubbuildout
Author: Kevin Williams
Author-email: kevin@weblivion.com
License: ZPL 2.1
Description: ====================
        Buildout from GitHub
        ====================
        
        GitHub has become a commonly-used SCM tool for software engineering teams.
        The purpose of this Buildout extension is to enable the retrieval of source
        tarballs and static downloads from private repositories by using the API v3's
        token-based authentication, combined with a bit of URL rewriting to retrieve
        files using the API server instead of the main website when required.
        
        Please see the sections below for setup and usage instructions.
        
        
        Request an API Key
        ------------------
        
        Before you can access private repositories from this module, you must create
        and store an API key on each system running buildout. Unlike the v2 API where
        one key was issued per user, you may create as many keys as you like and
        revoke them at will.
        
        API keys are tied to an individual user account.
        
        You can create API v3 key using ``curl`` (please substitute your own GitHub
        user name)::
        
            curl -s -X POST -d '{"scopes": ["repo"]}' -u ${user} \
                https://api.github.com/authorizations | grep token
        
        Important Note: You MUST specify the scopes attribute to secure access to
        private repositories; leaving the scope blank provides read-only access to
        public data.
        
        If you plan to make multiple keys for distribution to different systems (e.g.
        automated build environment), you might want to include a description to be
        able to distinguish them from one another later::
        
            curl -s -X POST -d '{"note": "build001.mydomain.ext", "scopes": ["repo"]}' \
                -u ${user} https://api.github.com/authorizations | grep token
        
        
        Store API Key in Git Config
        ---------------------------
        
        Now configure the value of github.accesstoken to the hash returned from the 
        command above::
        
            git config --global github.accesstoken ${token}
        
        For details on managing authorization GitHub's OAuth tokens, see the API
        documentation: http://developer.github.com/v3/oauth/#oauth-authorizations-api
        
        
        GitHub Repository Downloads
        ---------------------------
        
        You can instruct Buildout to download a tarball of any refid from your
        repository by specifying the same URL as you would use in your browser to
        retrieve it, using the following syntax::
        
            https://github.com/${user}/${project}/${archivetype}/${refid}
        
        **Important Note:** The url *must* use the ``https`` protocol to be retrieved
        using this extension; URLs using the ``http`` protocol will be ignored.
        
        In practice, you would typically use this to retrieve a tarball for
        installation as an egg in your buildout file, using a recipe similar to this::
        
            [buildout]
            find-links =
                https://github.com/me/myproject/tarball/master#egg=myproject
        
            eggs = myproject
        
            parts = myproject
        
            [myproject]
            unzip = true
            recipe = zc.recipe.egg
            path = myproject
        
        Note: These URLs will be rewritten during retrieval to use the API v3 URL instead.
        If you wish, you can explicitly specify the API server URL for retriving the file::
        
            https://api.github.com/repo/me/myproject/tarball/master
        
        
        GitHub Static Downloads (DEPRECATED)
        ------------------------------------
        
        IMPORTANT NOTE: Support for static downloads has been deprecated by GitHub
        as of 2012-12-11 and will be removed "in 90 days" (on or around 2013-03-11).
        If your project depends on this feature, now would be a good time to make
        alternate plans. For details, see the link below:
        
            https://github.com/blog/1302-goodbye-uploads
        
        Static downloads that have been previously uploaded to your GitHub project
        may also be retrieved using the same URL you would use in your browser,
        formed as follows::
        
            https://github.com/downloads/${user}/${project}/${filename}
        
        **Important Note:** As with repository downloads, the url *must* use the
        ``https`` protocol to be retrieved.
        
        Since these files can contain static software releases as eggs or anything
        else you want (media files, configuration data, etc.) it is up to you how
        to use them in your buildout; a common pattern is to install them as a part
        in a fashion similar to the following example::
        
            [buildout]
            parts = mypart
        
            [mypart]
            recipe = hexagonit.recipe.download
            url = https://github.com/downloads/me/myproject/myfile.tar.gz
        
        
        Credits
        -------
        
        Thanks to Bernd Dorn, Jürgen Kartnaller, Bernd Rössl and the rest at Lovely
        Systems for lovely.buildouthttp (upon which this project is based), and to
        Clayton Parker and Tarek Ziade for bugfixes and extensions.
        
        
        
        =========================
        Changes to githubbuildout
        =========================
        
        2013-04-25 0.2:
        ---------------
        
        - Declare a user agent to comply with GitHub's new API requirement (see
          http://developer.github.com/changes/2013-04-24-user-agent-required/):
          `githubbuildout/$version zc.buildout`
        
        
        2012-06-21 0.1:
        ---------------
        
        - Initial Release (based on lovely.buildouthttp)
        
        
        
Keywords: buildout github private repository download
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Zope Public License
Classifier: Framework :: Buildout :: Extension
Classifier: Topic :: Software Development :: Build Tools
