Movatterモバイル変換

[0]ホーム
URL:

Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

 Sign up
Appearance settings
This repository was archived by the owner on Nov 1, 2017. It is now read-only.

Commit8351fe1

Browse files
author
hubot
committed
Merge pull request#537 from github/update-1403025384
2 parents54eab23 +55592de commit8351fe1

File tree

6 files changed

+375
-1
lines changed

6 files changed

+375
-1
lines changed
Lines changed: 120 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,120 @@
1+
---
2+
title:Managing deploy keys | GitHub API
3+
---
4+
5+
#Managing Deploy Keys
6+
7+
* TOC
8+
{:toc}
9+
10+
There are four ways to manage SSH keys on your servers when automating deployment scripts:
11+
12+
* SSH agent forwarding
13+
* HTTPS with OAuth tokens
14+
* Deploy keys
15+
* Machine users
16+
17+
This guide will help you decide what strategy is best for you.
18+
19+
##SSH agent forwarding
20+
21+
In many cases, especially in the beginning of a project, SSH agent forwarding is the quickest and simplest method to use. Agent forwarding uses the same SSH keys that your local development computer uses.
22+
####Pros
23+
24+
* You do not have to generate or keep track of any new keys.
25+
* There is no key management; users have the same permissions on the server that they do locally.
26+
* No keys are stored on the server, so in case the server is compromised, you don't need to hunt down and remove the compromised keys.
27+
28+
####Cons
29+
30+
* Users**must** SSH in to deploy; automated deploy processes can't be used.
31+
* SSH agent forwarding can be troublesome to run for Windows users.
32+
33+
####Setup
34+
35+
1. Turn on agent forwarding locally. See[our guide on SSH agent forwarding][ssh-agent-forwarding] for more information.
36+
2. Set your deploy scripts to use agent forwarding. For example, on a bash script, enabling agent forwarding would look something like this:`ssh -A serverA 'bash -s' < deploy.sh`
37+
38+
##HTTPS cloning with OAuth tokens
39+
40+
If you don't want to use SSH keys, you can use[HTTPS with OAuth tokens][git-automation].
41+
42+
####Pros
43+
44+
* Anyone with access to the server can deploy the repository.
45+
* Users don't have to change their local SSH settings.
46+
* Multiple tokens (one for each user) are not needed; one token per server is enough.
47+
* A token can be revoked at any time, turning it essentially into a one-use password.
48+
* Generating new tokens can be easily scripted using[the OAuth API](https://developer.github.com/v3/oauth_authorizations/#create-a-new-authorization)
49+
50+
####Cons
51+
52+
* You must make sure that you configure your token with the correct access scopes.
53+
* Tokens are essentially passwords, and must be protected the same way.
54+
55+
####Setup
56+
57+
See[our guide on Git automation with tokens][git-automation].
58+
59+
##Deploy keys
60+
61+
A deploy key is an SSH key that is stored on your server and grants access to a single GitHub repository. This key is attached directly to the repository instead of to a personal user account.
62+
63+
####Pros
64+
65+
* Anyone with access to the repository and server has the ability to deploy the project.
66+
* Users don't have to change their local SSH settings.
67+
68+
####Cons
69+
70+
* Deploy keys only grant access to a single repository. More complex projects may have many repositories to pull to the same server.
71+
* The key has full read/write access to the repository.
72+
* Deploy keys are usually not protected by a passphrase, making the key easily accessible if the server is compromised.
73+
74+
####Setup
75+
76+
1.[Run the`ssh-keygen` procedure][generating-ssh-keys] on your server.
77+
2. In the top right corner of any GitHub page, click your profile photo.
78+
![Sample of an avatar](https://github-images.s3.amazonaws.com/help/profile/top_right_avatar.png)
79+
3. On your profile page, click the**Repositories** tab, then click the name of your repository.
80+
![Repository tab](https://github-images.s3.amazonaws.com/help/profile/profile_repositories_tab.png)
81+
4. In your repository's right sidebar, click**Settings**.
82+
![Settings tab](https://github-images.s3.amazonaws.com/help/repository/repo-actions-settings.png)
83+
3. In the sidebar, click**Deploy Keys**.
84+
![Deploy Keys section](/images/deploy-keys.png)
85+
3. Click**Add deploy key**. Paste your public key in and submit.
86+
![Add Deploy Key button](https://github-images.s3.amazonaws.com/help/repository/repo-deploy-key.png)
87+
88+
##Machine users
89+
90+
If your server needs to access multiple repositories, you can choose to attach an SSH key to an automated user account. Since this account won't be used by a human, it's called a machine user. You can then[add the machine account as collaborator][collaborator] or[add the machine user to a team][team] with access to the repositories it needs to manipulate.
91+
92+
<divclass="alert">
93+
<p>
94+
<strong>Tip</strong>: Our <ahref="https://help.github.com/articles/github-terms-of-service">terms of service</a> do mention that <em>'Accounts registered by "bots" or other automated methods are not permitted.'</em> and that <em>'One person or legal entity may not maintain more than one free account.'</em> But don't fear, we won't send rabid lawyers out to hunt you down if you make machine users for your server deploy scripts. Machine users are completely kosher.
95+
</p>
96+
</div>
97+
98+
####Pros
99+
100+
* Anyone with access to the repository and server has the ability to deploy the project.
101+
* No (human) users need to change their local SSH settings.
102+
* Multiple keys are not needed; one per server is adequate.
103+
* Organizations can give read-only access to their machine users.
104+
105+
####Cons
106+
107+
* By default, the key has full read/write access to the repository if the repository belongs to a user account. You can add the machine user to a read-only team if it's accessing repositories in an organization.
108+
* Machine user keys, like deploy keys, are usually not protected by a passphrase.
109+
110+
####Setup
111+
112+
1.[Run the`ssh-keygen` procedure][generating-ssh-keys] on your server and attach the public key to the machine user account.
113+
2. Give that account access to the repositories it will need to access. You can do this by[adding the account as collaborator][collaborator] or[adding it to a team][team] in an organization.
114+
115+
[ssh-agent-forwarding]:/guides/using-ssh-agent-forwarding/
116+
[generating-ssh-keys]:https://help.github.com/articles/generating-ssh-keys
117+
[tos]:https://help.github.com/articles/github-terms-of-service
118+
[git-automation]:https://help.github.com/articles/git-automation-with-oauth-tokens
119+
[collaborator]:https://help.github.com/articles/how-do-i-add-a-collaborator
120+
[team]:https://help.github.com/articles/adding-organization-members-to-a-team
Lines changed: 136 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,136 @@
1+
---
2+
title:Using SSH Agent Forwarding | GitHub API
3+
---
4+
5+
#Using SSH agent forwarding
6+
7+
* TOC
8+
{:toc}
9+
10+
SSH agent forwarding can be used to make deploying to a server simple. It allows you to use your local SSH keys instead of leaving keys (without passphrases!) sitting on your server.
11+
12+
If you've already set up an SSH key to interact with GitHub, you're probably familiar with`ssh-agent`. It's a program that runs in the background and keeps your key loaded into memory, so that you don't need to enter your passphrase every time you need to use the key. The nifty thing is, you can choose to let servers access your local`ssh-agent` as if they were already running on the server. This is sort of like asking a friend to enter their password so that you can use their computer.
13+
14+
Check out[Steve Friedl's Tech Tips guide][tech-tips] for a more detailed explanation of SSH agent forwarding.
15+
16+
##Setting up SSH agent forwarding
17+
18+
Ensure that your own SSH key is set up and working. You can use[our guide on generating SSH keys][generating-keys] if you've not done this yet.
19+
20+
You can test that your local key works by entering`ssh -T git@github.com` in the terminal:
21+
22+
<preclass="terminal">
23+
$ ssh -T git@github.com
24+
<spanclass="comment"># Attempt to SSH in to github</span>
25+
<spanclass="output">Hi <em>username</em>! You've successfully authenticated, but GitHub does not provide</span>
26+
<spanclass="output">shell access.</span>
27+
</pre>
28+
29+
We're off to a great start. Let's set up SSH to allow agent forwarding to your server.
30+
31+
1. Using your favorite text editor, open up the file at`~/.ssh/config`. If this file doesn't exist, you can create it by entering`touch ~/.ssh/config` in the terminal.
32+
33+
2. Enter the following text into the file, replacing`example.com` with your server's domain name or IP:
34+
35+
Host example.com
36+
ForwardAgent yes
37+
38+
<divclass="warning">
39+
<p>
40+
<strong>Warning</strong>: You may be tempted to use a wildcard like <code>Host*</code> to just apply this setting to all SSH connections. That's not really a good idea, as you'd be sharing your local SSH keys with <em>every</em> server you SSH into. They won't have direct access to the keys, but they will be able to use them <em>as you</em> while the connection is established. <strong>You should only add servers you trust and that you intend to use with agent forwarding.</strong>
41+
</p>
42+
</div>
43+
44+
##Testing SSH agent forwarding
45+
46+
To test that agent forwarding is working with your server, you can SSH into your server and run`ssh -T git@github.com` once more. If all is well, you'll get back the same prompt as you did locally.
47+
48+
If you're unsure if your local key is being used, you can also inspect the`SSH_AUTH_SOCK` variable on your server:
49+
50+
<preclass="terminal">
51+
$ echo "$SSH_AUTH_SOCK"
52+
<spanclass="comment"># Print out the SSH_AUTH_SOCK variable</span>
53+
<spanclass="output">/tmp/ssh-4hNGMk8AZX/agent.79453</span>
54+
</pre>
55+
56+
If the variable is not set, it means that agent forwarding is not working:
57+
58+
<preclass="terminal">
59+
$ echo "$SSH_AUTH_SOCK"
60+
<spanclass="comment"># Print out the SSH_AUTH_SOCK variable</span>
61+
<spanclass="output"><em>[No output]</em></span>
62+
$ ssh -T git@github.com
63+
<spanclass="comment"># Try to SSH to github</span>
64+
<spanclass="output">Permission denied (publickey).</span>
65+
</pre>
66+
67+
##Troubleshooting SSH agent forwarding
68+
69+
Here are some things to look out for when troubleshooting SSH agent forwarding.
70+
71+
###Your SSH keys must work locally
72+
73+
Before you can make your keys work through agent forwarding, they must work locally first.[Our guide on generating SSH keys][generating-keys] can help you set up your SSH keys locally.
74+
75+
###Your system must allow SSH agent forwarding
76+
77+
Sometimes, system configurations disallow SSH agent forwarding. You can check if a system configuration file is being used by entering the following command in the terminal:
78+
79+
<preclass="terminal">
80+
$ ssh -v <em>example.com</em>
81+
<spanclass="comment"># Connect to example.com with verbose debug output</span>
82+
<spanclass="output">OpenSSH_5.6p1, OpenSSL 0.9.8r 8 Feb 2011</span>
83+
<spanclass="output">debug1: Reading configuration data /Users/<em>you</em>/.ssh/config</span>
84+
<spanclass="output">debug1: Applying options for example.com</span>
85+
<spanclass="output">debug1: Reading configuration data /etc/ssh_config</span>
86+
<spanclass="output">debug1: Applying options for *</span>
87+
$ exit
88+
<spanclass="comment"># Returns to your local command prompt</span>
89+
</pre>
90+
91+
In the example above, the file*~/.ssh/config* is loaded first, then*/etc/ssh_config* is read. We can inspect that file to see if it's overriding our options by running the following commands:
92+
93+
<preclass="terminal">
94+
$ cat /etc/ssh_config
95+
<spanclass="comment"># Print out the /etc/ssh_config file</span>
96+
<spanclass="output"> Host *</span>
97+
<spanclass="output"> SendEnv LANG LC_*</span>
98+
<spanclass="output"> ForwardAgent no</span>
99+
</pre>
100+
101+
In this example, our*/etc/ssh_config* file specifically says`ForwardAgent no`, which is a way to block agent forwarding. Deleting this line from the file should get agent forwarding working once more.
102+
103+
###Your server must allow SSH agent forwarding on inbound connections
104+
105+
Agent forwarding may also be blocked on your server. You can check that agent forwarding is permitted by SSHing into the server and running`sshd_config`. The output from this command should indicate that`AllowAgentForwarding` is set.
106+
107+
###Your local`ssh-agent` must be running
108+
109+
On most computers, the operating system automatically launches`ssh-agent` for you. On Windows, however, you need to do this manually. We have[a guide on how to start`ssh-agent` whenever you open Git Bash][autolaunch-ssh-agent].
110+
111+
To verify that`ssh-agent` is running on your computer, type the following command in the terminal:
112+
113+
<preclass="terminal">
114+
$ echo "$SSH_AUTH_SOCK"
115+
<spanclass="comment"># Print out the SSH_AUTH_SOCK variable</span>
116+
<spanclass="output">/tmp/launch-kNSlgU/Listeners</span>
117+
</pre>
118+
119+
###Your key must be available to`ssh-agent`
120+
121+
You can check that your key is visible to`ssh-agent` by running the following command:
122+
123+
<preclass="terminal">
124+
ssh-add -L
125+
</pre>
126+
127+
If the command says that no identity is available, you'll need to add your key:
128+
129+
<preclass="terminal">
130+
ssh-add <em>yourkey</em>
131+
</pre>
132+
133+
[tech-tips]:http://www.unixwiz.net/techtips/ssh-agent-forwarding.html
134+
[generating-keys]:https://help.github.com/articles/generating-ssh-keys
135+
[ssh-passphrases]:https://help.github.com/ssh-key-passphrases/
136+
[autolaunch-ssh-agent]:https://help.github.com/articles/working-with-ssh-key-passphrases#auto-launching-ssh-agent-on-msysgit

‎layouts/guides.html‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,8 @@ <h2><a href="/v3/">API</a></h2>
3030
<li><h3><ahref="/guides/traversing-with-pagination/">Traversing with pagination</a></h3></li>
3131
<li><h3><ahref="/guides/building-a-ci-server/">Building a CI server</a></h3></li>
3232
<li><h3><ahref="/guides/delivering-deployments/">Delivering deployments</a></h3></li>
33+
<li><h3><ahref="/guides/managing-deploy-keys/">Managing deploy keys</a></h3></li>
34+
<li><h3><ahref="/guides/using-ssh-agent-forwarding/">Using SSH agent forwarding</a></h3></li>
3335
</ul>
3436
</div>
3537

‎static/css/documentation.css‎

Lines changed: 93 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -114,6 +114,7 @@ h3 {
114114
}
115115

116116
h4 {
117+
margin:1em0;
117118
position: relative;
118119
}
119120

@@ -974,6 +975,80 @@ a .mega-octicon {
974975
margin:12px0;
975976
}
976977

978+
/* Taken from Help in order to show images in ordered lists inline */
979+
ol {
980+
counter-reset: li;
981+
list-style: none;
982+
position: relative;
983+
padding-bottom:10px;
984+
}
985+
ol>li {
986+
padding:5px05px55px;
987+
position: relative;
988+
margin-bottom:5px;
989+
}
990+
ol>li:before {
991+
content:counter(li);
992+
counter-increment: li;
993+
position: absolute;
994+
top:0;
995+
left:0;
996+
height:100%;
997+
width:30px;
998+
padding:010px00;
999+
color:#999;
1000+
font-size:22px;
1001+
font-weight: bold;
1002+
line-height:35px;
1003+
text-align: right;
1004+
border-right:1px solid#ddd;
1005+
}
1006+
ol>li>p:first-child {
1007+
margin-top:0;
1008+
}
1009+
ol>li:after {
1010+
content:".";
1011+
display: block;
1012+
clear: both;
1013+
visibility: hidden;
1014+
line-height:0;
1015+
height:0;
1016+
}
1017+
.contentol>liimg {
1018+
max-width:100px;
1019+
margin:00010px;
1020+
float: right;
1021+
border:1px solid#ddd;
1022+
cursor: pointer;
1023+
}
1024+
.contentol>liimg.expanded {
1025+
max-width:400px;
1026+
}
1027+
1028+
.content .full-image {
1029+
position: absolute;
1030+
top:5px;
1031+
right:-20px;
1032+
z-index:100;
1033+
}
1034+
.content .full-imageimg {
1035+
position: absolute;
1036+
top:0;
1037+
right:20px;
1038+
margin:0;
1039+
max-width:600px;
1040+
box-shadow:003pxrgba(0,0,0,0.2);
1041+
}
1042+
.content .full-image:hover .octicon, .full-image:hover .mini-icon {
1043+
color:#666;
1044+
}
1045+
.content .full-image .octicon, .full-image .octicon-remove-close {
1046+
position: absolute;
1047+
top:0px;
1048+
right:0px;
1049+
color:#999;
1050+
cursor: pointer;
1051+
}
9771052

9781053
.content .description {
9791054
margin-left:20px;
@@ -1174,6 +1249,14 @@ pre span.comment {color: #aaa;}
11741249
color:#f9fe64;
11751250
}
11761251

1252+
.terminalspan.comment {
1253+
color:#ccc;
1254+
}
1255+
1256+
.terminalspan.output {
1257+
color:#63E463;
1258+
}
1259+
11771260
/****************************/
11781261
/* Expandable List Module */
11791262
/****************************/
@@ -1217,12 +1300,21 @@ pre span.comment {color: #aaa;}
12171300
.alert {
12181301
position:relative;
12191302
padding:015px;
1220-
color:#264c72;
1303+
color:#264c72;
12211304
border:1px solid#97c1da;
12221305
border-radius:3px;
12231306
background-color:#d8ebf8;
12241307
}
12251308

1309+
.warning {
1310+
position:relative;
1311+
padding:015px;
1312+
color:#613A00;
1313+
border:1px solid#dca874;
1314+
border-radius:3px;
1315+
background-color:#ffe3c8;
1316+
}
1317+
12261318
/*------------------------------------------------------------------------------
12271319
Dev Program
12281320
------------------------------------------------------------------------------*/

‎static/images/deploy-keys.png‎

24.5 KB
Loading

0 commit comments

Comments
 (0)
[8]ページ先頭
©2009-2025 Movatter.jp