Clarify documentation on how to add custom Omniauth provider to GitLab
Created by: tdm00
Clarify the directions on how to add custom Omniauth provider to GitLab..
Merge request reports
Activity
Created by: tdm00
@jacobvosmaer this should merge cleanly and removes the references to the images.
By Administrator on 2013-07-29T13:20:29 (imported from GitLab project)
By Administrator on 2013-07-29T13:20:29 (imported from GitLab)
361 361 362 362 These steps are fairly general and you will need to figure out the exact details from the Omniauth provider's documentation. Created by: jacobvosmaer
Would it be possible to refer to the earlier point in the install guide where the
bundle installcommand is spelled out? If we repeat the incantations here they are sure to get out of date at some point.By Administrator on 2013-08-08T14:17:17 (imported from GitLab project)
By Administrator on 2013-08-08T14:17:17 (imported from GitLab)
361 361 362 362 These steps are fairly general and you will need to figure out the exact details from the Omniauth provider's documentation. Created by: jacobvosmaer
Something like 'run the appropriate
bundle installcommand for your setup from the Install Gems section'By Administrator on 2013-08-08T14:17:17 (imported from GitLab project)
By Administrator on 2013-08-08T14:17:17 (imported from GitLab)
Created by: coveralls
Coverage decreased (-0%) when pulling d99ea6e0cd580cbe1027a512c2e6913d3bf66ce0 on tdm00:clarify-adding-custom-oauth-provider into b55e22e2 on gitlabhq:master.
By Administrator on 2013-07-29T13:44:57 (imported from GitLab project)
By Administrator on 2013-07-29T13:44:57 (imported from GitLab)
Created by: tdm00
I don't believe so as the switches are different in the command.
On Monday, July 29, 2013, Coveralls wrote:
[image: Coverage Status] https://coveralls.io/builds/133811
Coverage remained the same when pulling *d99ea6ehttps://github.com/gitlabhq/gitlabhq/commit/d99ea6e0cd580cbe1027a512c2e6913d3bf66ce0on tdm00:clarify-adding-custom-oauth-provider
- into *b55e22ehttps://github.com/gitlabhq/gitlabhq/commit/b55e22e277bd754d4ab89c046ccbe8f943730c8don gitlabhq:master *.
— Reply to this email directly or view it on GitHubhttps://github.com/gitlabhq/gitlabhq/pull/4664#issuecomment-21720014 .
Troy Murray
By Administrator on 2013-07-29T14:12:04 (imported from GitLab project)
By Administrator on 2013-07-29T14:12:04 (imported from GitLab)
Created by: tdm00
Because of how the Gemfile.lock works in production mode with a Rails app.
See https://groups.google.com/d/msg/gitlabhq/FBT4Un-81nA/5494fVq-QewJ for more info
On Mon, Jul 29, 2013 at 10:28 AM, Jacob Vosmaer notifications@github.comwrote:
I see. Any idea why that is necessary?
— Reply to this email directly or view it on GitHubhttps://github.com/gitlabhq/gitlabhq/pull/4664#issuecomment-21723427 .
Troy Murray
By Administrator on 2013-07-29T14:54:39 (imported from GitLab project)
By Administrator on 2013-07-29T14:54:39 (imported from GitLab)
Created by: jacobvosmaer
This is a tricky one; I think the Bundler difficulties are a symptom indicating that there should be a better way to do this. Some ideas:
- Make the changes to the Gemfile on a development machine and run
bundle installthere. Then commit or create a patch, apply that on the server, and you can run the prescribed bundle command. - Maybe it works if you take the
bundlecommand earlier in the document and simply add--no-deployment --path vendor/bundleat the end. Could be that that overrides the--deployment.
I think it is important that the instructions do not steer people in the direction of making a mess of their installation. What do you think @tdm00?
By Administrator on 2013-08-01T14:21:46 (imported from GitLab project)
By Administrator on 2013-08-01T14:21:46 (imported from GitLab)
- Make the changes to the Gemfile on a development machine and run
Created by: tdm00
Personally I feel that if a person is at the point of trying to add their own custom provider then they're knowledgeable enough to handle these additional instructions. Having to setup a new development environment to make this one change when you can do it with the command I've outlined seems like it's adding a while lot more work for the same end result solution.
Personally I prefer the whole command provided so you can easily copy and paste, which removes greater opportunity for a typographical mistake. If we outline that they just add the additional switches they have to type out everything, or scroll up, find the right command, copy, paste, scroll down, get the new parameters, copy, paste. Is it just me or does this start to feel like we're creating more work for the user?
I can understand the value in trying to reuse sections of the documentation and not have to maintain extra additional parts. However this is really two line changes that seem to make sense, at least to me, to spell out.
That's my thoughts, but it's your project so you have the final say.
On Aug 1, 2013, at 10:22 AM, Jacob Vosmaer notifications@github.com wrote:
This is a tricky one; I think the Bundler difficulties are a symptom indicating that there should be a better way to do this. Some ideas:
Make the changes to the Gemfile on a development machine and run bundle install there. Then commit or create a patch, apply that on the server, and you can run the prescribed bundle command. Maybe it works if you take the bundle command earlier in the document and simply add --no-deployment --path vendor/bundle at the end. Could be that that overrides the --deployment. I think it is important that the instructions do not steer people in the direction of making a mess of their installation. What do you think @tdm00?
— Reply to this email directly or view it on GitHub.
By Administrator on 2013-08-01T15:02:30 (imported from GitLab project)
By Administrator on 2013-08-01T15:02:30 (imported from GitLab)
361 361 362 362 These steps are fairly general and you will need to figure out the exact details from the Omniauth provider's documentation. Created by: jacobvosmaer
I have tried the following procedure and it seems to work:
- edit Gemfile;
- run
(bundle command with --deployment somewhere) --no-deployment --path vendor/bundle.
How about the following:
To download and install your omniauth gem run the [`bundle install` command for your setup](#install-gems). If necessary you can add the following options to the `bundle install` command to override Bundler's deployment mode: ` --no-deployment --path vendor/bundle`.Looking back at your experience do you think that would have helped @tdm00?
By Administrator on 2013-08-08T14:17:17 (imported from GitLab project)
By Administrator on 2013-08-08T14:17:17 (imported from GitLab)
Created by: jacobvosmaer
@tdm00 thank you for elaborating on the user perspective; you know more about that than me.
My concern is that we have limited maintenance resources and the fact that adding a custom omniauth-gem is an advanced feature. When the documentation for a less frequently used feature breaks it can slip by unnoticed for quite some time. That is why I would like to not only bring the documentation to a state where it gives instructions that work, but also to reduce the chance that it will break again in the future.
By Administrator on 2013-08-05T10:15:16 (imported from GitLab project)
By Administrator on 2013-08-05T10:15:16 (imported from GitLab)
361 361 362 362 These steps are fairly general and you will need to figure out the exact details from the Omniauth provider's documentation. Created by: tdm00
I don't think this would have helped as I find it to vague and confusing. If I read this I would have next done a Google search to find someone that has successfully added a customer provider and l looked for instructions from them, like the ones I wrote.
On Aug 5, 2013, at 6:15 AM, Jacob Vosmaer notifications@github.com wrote:
In doc/install/installation.md:
- Add
gem "omniauth-your-auth-provider"to the Gemfile -* Runsudo -u git -H bundle installto install the new gem(s) +* Runsudo -u git -H bundle install --without development test postgres --path vendor/bundle --no-deployto install the new gem(s) with MySQL andsudo -u git -H bundle install --without development test mysql --path vendor/bundle --no-deployto install with PostgreSQL I have tried the following procedure and it seems to work:
edit Gemfile; run (bundle command with --deployment somewhere) --no-deployment --path vendor/bundle. How about the following:
To download and install your omniauth gem run the
bundle installcommand for your setup. If necessary you can add the following options to thebundle installcommand to override Bundler's deployment mode:--no-deployment --path vendor/bundle. Looking back at your experience do you think that would have helped @tdm00?— Reply to this email directly or view it on GitHub.
By Administrator on 2013-08-08T14:17:17 (imported from GitLab project)
By Administrator on 2013-08-08T14:17:17 (imported from GitLab)
- Add
Created by: tdm00
At this point I'll be performing these steps, or whatever is their equivalent, each month as I update our installs, including the one using puppet.
Since the current set of steps are incorrect, at least for 5.2 - 5.4, I'm going to post these instructions in the Google Group as well, so at least they're documented somewhere for others, in addition to the StackOverflow Q/A that I posted.
On Aug 5, 2013, at 6:15 AM, Jacob Vosmaer notifications@github.com wrote:
@tdm00 thank you for elaborating on the user perspective; you know more about that than me.
My concern is that we have limited maintenance resources and the fact that adding a custom omniauth-gem is an advanced feature. When the documentation for a less frequently used feature breaks it can slip by unnoticed for quite some time. That is why I would like to not only bring the documentation to a state where it gives instructions that work, but also to reduce the chance that it will break again in the future.
— Reply to this email directly or view it on GitHub.
By Administrator on 2013-08-05T10:54:52 (imported from GitLab project)
By Administrator on 2013-08-05T10:54:52 (imported from GitLab)
Created by: jacobvosmaer
I talked to others on the team and they convinced me I was being too cautious. Let's do your approach with the full
bundle installcommand.By Administrator on 2013-08-06T07:30:55 (imported from GitLab project)
By Administrator on 2013-08-06T07:30:55 (imported from GitLab)
361 361 362 362 These steps are fairly general and you will need to figure out the exact details from the Omniauth provider's documentation. Created by: jacobvosmaer
OK let's do it like you suggested. BTW, which version of bundler do you use? I have to use
--no-deploymentinstead of--no-deploy.By Administrator on 2013-08-08T14:17:17 (imported from GitLab project)
By Administrator on 2013-08-08T14:17:17 (imported from GitLab)
361 361 362 362 These steps are fairly general and you will need to figure out the exact details from the Omniauth provider's documentation. 361 361 362 362 These steps are fairly general and you will need to figure out the exact details from the Omniauth provider's documentation. Created by: jacobvosmaer
The
--no-deployin your commit does not work for me:gigantor:gitlab-shell jacobvosmaer$ bundle -v Bundler version 1.3.5 $ bundle install --no-deploy Unknown switches '--no-deploy' $ bundle install --no-deployment Using addressable (2.3.2) ...By Administrator on 2013-08-08T14:17:17 (imported from GitLab project)
By Administrator on 2013-08-08T14:17:17 (imported from GitLab)
Created by: coveralls
Coverage decreased (-0%) when pulling 511ea7fe8e549c2abcd6dba9d3979a8a1c46559f on tdm00:clarify-adding-custom-oauth-provider into b55e22e2 on gitlabhq:master.
By Administrator on 2013-08-07T14:23:34 (imported from GitLab project)
By Administrator on 2013-08-07T14:23:34 (imported from GitLab)
361 361 362 362 These steps are fairly general and you will need to figure out the exact details from the Omniauth provider's documentation. Created by: jacobvosmaer
The
--no-deploytypo was in there twice, you forgot one. :)I just noticed that the install gems section also excludes the unicorn and aws groups.
Maybe we could add
This is the same command you used in the [Install Gems section](#install-gems) with `--path vendor/bundle --no-deployment` instead of `--deployment`.That way people can copy-paste the command, but also understand its intention.
By Administrator on 2013-08-08T14:17:17 (imported from GitLab project)
By Administrator on 2013-08-08T14:17:17 (imported from GitLab)
Created by: tdm00
OK, I'm not a git rebase pro, but I believe I've squashed all of the commits into a single commit for you AND I rebased the branch to the current gitlabhq/master so things should merge really easily.
By Administrator on 2013-08-08T14:19:17 (imported from GitLab project)
By Administrator on 2013-08-08T14:19:17 (imported from GitLab)
Created by: jacobvosmaer
Thanks again @tdm00
By Administrator on 2013-08-08T14:25:05 (imported from GitLab project)
By Administrator on 2013-08-08T14:25:05 (imported from GitLab)
