Deploy api_key: "GITHUB OAUTH TOKEN" ambiguity

Travis CI Discussions & Feedback
1

Looking at the docs Deployment page it’s not at all obvious to me what exactly api_key: "GITHUB OAUTH TOKEN" means. Should I use “GITHUB OAUTH TOKEN” literally as shown, or is it a placeholder for a token, which should be used in place of “GITHUB OAUTH TOKEN”?
From quite a long research on the Net, it seems the meaning is indeed the Personal Access Token, which have to be generated specifically for the task of uploading. However the interpretation of using “GITHUB OAUTH TOKEN” literally can be justified. Travis already has access to my GitHub account, as can be seen on Authorized OAuth Apps list on my account settings, and uses an OAUTH token for this, so “GITHUB OAUTH TOKEN” may quite well refer to that token.
There is a whole story behind the “GITHUB OAUTH TOKEN”, which the docs completely fail to hint.

2

It’s a placeholder.

https://docs.travis-ci.com/user/deployment/releases/#authenticating-with-an-oauth-token has the information about this token.

The code you are viewing is, as the section’s title says, “Examples of Conditional Deployment”, not an authoritative documentation for the Github Releases deployment. They are showcasing a completely different thing.

3

Thanks for explaining your confusion. As mentioned above by @native-api, GITHUB OAUTH TOKEN is meant to be a place holder. I appreciate the explanation that it could be construed as a special magic sequence to make something magical happen; it is a balancing act to find how we should explain these things. If you have a better idea to explain it, we appreciate your contribution (by clicking on the button on the upper right corner).

1 Like
4

I appreciate the replies to this confusion of mine.
@BanzaiMan - thumbs up for the ‘magic sequence’ metaphor:-)
@native-api I believe to have seen the example you are mentioning. Calling the same things different names in different parts of doc like ‘GITHUB_OAUTH_TOKEN’ and then ‘YOUR_API_KEY_ENCRYPTED’ arguably raises doubts, but not clears them.
I sure understand the difficulties of writing the docs.

The name for the placeholder would be arguably less ambiguous if written as YOUR_GITHUB_OAUTH_TOKEN.
But certainly a more descriptive explanation would be even better.

I dare say have some experience with GitHub and Travis, and still spent embarrassingly long time to figure the things out. I would be happy to find in the docs the following details:

The user is assumed to be familiar with the Public-key cryptography

“GITHUB OAUTH TOKEN” is a GitHub ‘Personal Access Token’ that needs to be generated on GitHub, and encrypted using the Travis Public RSA Key. The encrypted string then can be used as “GITHUB OAUTH TOKEN” on the Travis Yaml configuration file.

  1. Generate a GitHub ‘Personal Access Token’ HERE with the following scopes:
    read:org
    user:email
    repo_deployment
    repo:status
    write:repo_hook
    public_repo

  2. Obtain the Tavis public RSA key for your Git repository (say facebook/rocksdb)
    wget https://api.travis-ci.org/repos/facebook/rocksdb/key

    NOTES

    • entering the URL in browser won’t work, use wget or curl, or other facilities to read from URL.
    • The URL is in Travis API v1 format, which luckily doesn’t require the ‘Authorization: token’ (required in v3), which would complicate the procedure even more.
    • First time users dismiss the advise from Travis to use API v3. SURE use v1 to make your life easier.
    • The Json file is returned. Let’s call it travis_rsa_pubkey.json.
    • The Key has to be extracted from the Json into travis_rsa_pubkey.pem IF you intend to use it with OpenSSL instead of Travis command line client
    • fix the title in the key: replace ‘RSA PUBLIC KEY-----’ with ‘PUBLIC KEY-----’ (Important!)

  3. Encrypt the Token using the RSA key and OpenSSL, or travis Ruby client. A ‘long cypher string’ is returned
    echo -n 'GITHUB_OAUTH_TOKEN' | openssl pkeyutl -encrypt -inkey travis_rsa_pubkey.pem -pubin | base64 -w0

  4. Use the encrypted value i.e. the ‘long cypher string’ on the Travis Yaml

My hat is off for the authors of the following references:

  1. How to publish artifacts in Travis CI?
  2. Travis Issue #2982: How does “travis encrypt” work?
  3. GitHub Releases Uploading

Voila, something like that.