Skip to content

Commit 71efda3

Browse files
alan20854alan20854
committed
initial commit
0 parents  commit 71efda3

30 files changed

+905
-0
lines changed

‎.circleci/config.yml‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
version: 2.1
2+
3+
jobs:
4+
getting-started:
5+
docker:
6+
- image: circleci/node
7+
steps:
8+
- run:
9+
name: Getting Started
10+
command: |
11+
echo "Your orb is now building on CircleCI"
12+
echo "This is a temporary configuration file. Continue with the orb-init.sh script and follow the README.md to publish your orb."
13+
workflows:
14+
setup:
15+
jobs:
16+
- getting-started
17+
18+

‎.github/.gitignore‎

Whitespace-only changes.

‎.github/ISSUE_TEMPLATE/bug-report-.md‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
---
2+
name: Bug Report!
3+
about: File a bug report to let us know what's wrong!
4+
title: ''
5+
labels: bug
6+
assignees: ''
7+
8+
---
9+
10+
**Orb Version**
11+
The version number of the orb
12+
13+
<!--
14+
e.g., 1.0.0
15+
find this information in your config.yml file;
16+
if the version is @volatile, check the top of your CircleCI-generated,
17+
expanded configuration file, viewable from the "Configuration" tab of
18+
any job page, for the orb's specific semantic version number
19+
-->
20+
21+
**Describe the bug**
22+
<!---
23+
please include any relevant links to CircleCI workflows or jobs
24+
where you saw this behavior
25+
-->
26+
27+
**To Reproduce**
28+
29+
<!--
30+
Steps to reproduce the behavior:
31+
1. Go to '...'
32+
2. Click on '....'
33+
3. Scroll down to '....'
34+
4. See error
35+
-->
36+
37+
**Expected behavior**
38+
39+
<!--
40+
A clear and concise description of what you expected to happen.
41+
-->
42+
43+
**Additional context**
44+
45+
<!--
46+
Add any other context about the problem here.
47+
-->

‎.github/ISSUE_TEMPLATE/feature-request-.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
---
2+
name: Feature Request!
3+
about: Want something new to be incorporated into this orb?
4+
title: ''
5+
labels: enhancement
6+
assignees: ''
7+
8+
---
9+
10+
**Is your feature request related to a problem? Please describe.**
11+
A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
12+
13+
**Describe the solution you'd like**
14+
A clear and concise description of what you want to happen.
15+
16+
**Describe alternatives you've considered**
17+
A clear and concise description of any alternative solutions or features you've considered.
18+
19+
**Additional context**
20+
Add any other context about the feature request here.

‎.github/PULL_REQUEST_TEMPLATE/PULL_REQUEST_TEMPLATE.md‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
---
2+
name: Pull Request
3+
about: Default pull request template.
4+
title: ''
5+
labels: ''
6+
assignees: ''
7+
8+
---
9+
10+
### Checklist
11+
12+
<!--
13+
Thank you for contributing to CircleCI Orbs!
14+
before submitting your request, please go through the following
15+
items and place an x in the [ ] if they have been completed.
16+
-->
17+
18+
- [ ] All new jobs, commands, executors, parameters have descriptions
19+
- [ ] Examples have been added for any significant new features
20+
- [ ] README has been updated, if necessary
21+
22+
### Motivation, Related Issues
23+
24+
<!---
25+
Why is this change required? what problem does it solve?
26+
paste links to any relevant GitHub issues filed against
27+
this repository that this pull request addresses
28+
-->
29+
30+
### Description
31+
32+
<!---
33+
Describe your changes in details, preferably in an imperative mood,
34+
i.e., "add `commandA` to `jobB`"
35+
-->

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2019 Circle Internet Services, Inc.
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md‎

Lines changed: 164 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,164 @@
1+
# Orb Starter Kit [![CircleCI Build Status](https://circleci.com/gh/CircleCI-Public/orb-starter-kit.svg?style=shield "CircleCI Build Status")](https://circleci.com/gh/CircleCI-Public/orb-starter-kit) [![CircleCI Community](https://img.shields.io/badge/community-CircleCI%20Discuss-343434.svg)](https://discuss.circleci.com/c/ecosystem/orbs)
2+
3+
The Orb Starter Kit is a bash utility that makes creating your first orb a breeze!
4+
5+
**What are orbs?**
6+
Orbs are reusable [commands](https://circleci.com/docs/2.0/reusing-config/#authoring-reusable-commands), [executors](https://circleci.com/docs/2.0/reusing-config/#authoring-reusable-executors), and [jobs](https://circleci.com/docs/2.0/reusing-config/#jobs-defined-in-an-orb) (as well as [usage examples](https://github.com/CircleCI-Public/config-preview-sdk/blob/v2.1/docs/usage-examples.md))—snippets of CircleCI configuration—that can be shared across teams and projects. See [CircleCI Orbs](https://circleci.com/orbs), [Explore Orbs](https://circleci.com/orbs/registry), [Creating Orbs](https://circleci.com/docs/2.0/creating-orbs), and [Using Orbs](https://circleci.com/docs/2.0/using-orbs) for further information.
7+
8+
## What is in this kit?
9+
10+
This kit includes three main components:
11+
12+
* **Orb init script.**
13+
* The Orb init script will auytomatically generate for you a new GitHub repository with all of the source code needed to get started developing your own orb, complete with automation pipeline
14+
* **Hello World template.**
15+
* Within the [/src](https://github.com/CircleCI-Public/orb-starter-kit/tree/master/src) folder you can find find the destructured source of a simple "Hello World" orb. You can simply copy this code and begin hacking, or initialize it with our orb init script.
16+
* **Automated CI/CD Pipeline.**
17+
* After you run the init script you will also be automatically given a development pipeline to test and update your orb on CircleCI.
18+
* Automated Semver release process
19+
* Automated Integration Testing
20+
* No need to use CLI commands.
21+
22+
23+
24+
### Prerequisites
25+
26+
Before getting started you will need the the following things:
27+
1. A CircleCI [account](https://circleci.com/signup/).
28+
2. Git installed and configured locally.
29+
3. A CircleCI [Personal API Token](https://circleci.com/docs/2.0/managing-api-tokens/#creating-a-personal-api-token) (Must be Org admin to claim a namespace and publish production Orbs)
30+
31+
32+
33+
## Usage
34+
35+
### Getting started
36+
**1.** Clone this repo into a new directory with the name of your orb:
37+
38+
```
39+
git clone [email protected]:CircleCI-Public/orb-starter-kit.git My-Orb-Name
40+
```
41+
42+
**2.** Create a new repository on GitHub with the same name. https://github.com/new
43+
44+
**3.** Run the `orb-init.sh` script to begin.
45+
46+
[![asciicast](https://asciinema.org/a/oSc3M8uJri4zfo616wOVbh1lO.svg)](https://asciinema.org/a/oSc3M8uJri4zfo616wOVbh1lO)
47+
48+
The Orb Init script will automate the following tasks:
49+
50+
> * Install and update the CircleCI CLI
51+
> * Request a CircleCI API token if none is currently set.
52+
> * Check to ensure git is installed and authenticated with GitHub.
53+
> * Connect your repository with the blank repo created in step 2.
54+
> * Create and switch to an "Alpha" branch
55+
> * Walk through creating a new orb via the CircleCI CLI
56+
> * Allow you to optionally enable advanced features.
57+
> * Create your customized config file
58+
> * Clean up - The script will remove itself from the repo for the next commit.
59+
> * Commit alpha branch with changes to GitHub.
60+
61+
Your orb will now be available at `<your namespace>/<your orb>@dev:Alpha`
62+
63+
The script will end by giving you a link to the running automated pipeline on your CircleCI account which will be building a "Hello World" orb.
64+
65+
66+
67+
**4.** Begin editing.
68+
> You may now edit the contents of the `/src` folder and commit your changes to the `Alpha` branch or any non-master branch.
69+
70+
**5.** Build and test!
71+
> All commits to non-master branches will automatically result in the creation of a development orb under that branch. The automated pipeline will then run your integration tests against that newly created dev orb.
72+
73+
**6.** Publish!
74+
> Once ready to produce a new production version of your orb, you may merge your branch into the master branch to trigger the automated release process.
75+
>
76+
>**Recommended:** If you have enabled the `fail-if-semver-not-indicated` option, your commit message when merging to master _MUST_ include `[semver:patch|minor|major|skip]` to designate the release type.
77+
>
78+
> You will need to manually publish the production version of your Orb for the initial version before the automated pipeline can update your production version later on. This is not needed on subsequent pushes.
79+
80+
Once the orb is complete, you will have two new Green workflows in your CircleCI account. The first one is for the initial setup and the second one will have produced a development version of your orb which contains a sample Command, Executor, and Job.
81+
82+
83+
### Writing your orb
84+
This orb provides a basic directory/file structure for a decomposed orb (where commands, jobs, examples, and executors each live in their own YAML file). Create each of your commands, jobs, examples, and executors within the requisite folders in the `src` directory.
85+
86+
Following are some resources to help you build and test your orb:
87+
88+
- [Intro to authoring orbs](https://circleci.com/docs/2.0/orb-author-intro/#section=configuration)
89+
- [Orb Best Practices](https://circleci.com/docs/2.0/orbs-best-practices/#orb-best-practices-guidelines)
90+
- [How to make an easy and valuable open source contribution with CircleCI orbs](https://circleci.com/blog/how-to-make-an-easy-and-valuable-open-source-contribution-with-circleci-orbs/)
91+
92+
93+
### Permissions
94+
95+
Explanation of all permissions required for the script.
96+
97+
* **sudo** - The CircleCI CLI Update command will request sudo permissions to update.
98+
99+
### Preview
100+
101+
<details>
102+
<Summary>Preview "Hello-World" Orb produced by this repo by default.</Summary>
103+
104+
```yaml
105+
commands:
106+
greet:
107+
description: |
108+
Replace this text with a description for this command. # What will this command do? # Descriptions should be short, simple, and clear.
109+
parameters:
110+
greeting:
111+
default: Hello
112+
description: Select a proper greeting
113+
type: string
114+
steps:
115+
- run:
116+
command: echo << parameters.greeting >> world
117+
name: Hello World
118+
description: |
119+
Sample orb description # What will your orb allow users to do? # Descriptions should be short, simple, and clear.
120+
examples:
121+
example:
122+
description: |
123+
Sample example description. # What will this example document? # Descriptions should be short, simple, and clear.
124+
usage:
125+
jobs:
126+
build:
127+
machine: true
128+
steps:
129+
- foo/hello:
130+
username: Anna
131+
orbs:
132+
foo: bar/[email protected]
133+
version: 2.1
134+
executors:
135+
default:
136+
description: |
137+
This is a sample executor using Docker and Node. # What is this executor? # Descriptions should be short, simple, and clear.
138+
docker:
139+
- image: circleci/node:<<parameters.tag>>
140+
parameters:
141+
tag:
142+
default: latest
143+
description: |
144+
Pick a specific circleci/node image variant: https://hub.docker.com/r/circleci/node/tags
145+
type: string
146+
jobs:
147+
hello:
148+
description: |
149+
# What will this job do? # Descriptions should be short, simple, and clear.
150+
executor: default
151+
parameters:
152+
greeting:
153+
default: Hello
154+
description: Select a proper greeting
155+
type: string
156+
steps:
157+
- greet:
158+
greeting: << parameters.greeting >>
159+
orbs:
160+
hello: circleci/[email protected]
161+
version: 2.1
162+
```
163+
164+
</details>

‎_init/README_TEMPLATE.md‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
# <orb-name> Orb [![CircleCI Build Status](https://circleci.com/gh/<org-name>/<repo-name>.svg?style=shield "CircleCI Build Status")](https://circleci.com/gh/<org-name>/<repo-name>) [![CircleCI Orb Version](https://img.shields.io/badge/endpoint.svg?url=https://badges.circleci.io/orb/<orb-namespace>/<orb-name>)](https://circleci.com/orbs/registry/orb/<orb-namespace>/<orb-name>) [![GitHub License](https://img.shields.io/badge/license-MIT-lightgrey.svg)](https://raw.githubusercontent.com/<org-name>/<repo-name>/master/LICENSE) [![CircleCI Community](https://img.shields.io/badge/community-CircleCI%20Discuss-343434.svg)](https://discuss.circleci.com/c/ecosystem/orbs)
2+
3+
A description of your orb. Utilize this orb to easily add X to your CI/CD pipeline.
4+
5+
**TODO:**
6+
Publish your production orb! You may notice the badges above and links to the registry page below are not working yet, once you publish your first production version orb, these will begin to function.
7+
8+
What to do:
9+
* Make changes to your `Alpha` branch.
10+
* Flush out your integration test jobs
11+
* Merge to `master` with "`[semver:major]`" in the commit subject to publish 1.0.0 of your orb.
12+
13+
14+
## Usage
15+
16+
Example use-cases are provided on the orb [registry page](https://circleci.com/orbs/registry/orb/<orb-namespace>/<orb-name>#usage-examples). Source for these examples can be found within the `src/examples` directory.
17+
18+
19+
## Resources
20+
21+
[CircleCI Orb Registry Page](https://circleci.com/orbs/registry/orb/<orb-namespace>/<orb-name>) - The official registry page of this orb for all versions, executors, commands, and jobs described.
22+
[CircleCI Orb Docs](https://circleci.com/docs/2.0/orb-intro/#section=configuration) - Docs for using and creating CircleCI Orbs.
23+
24+
### How To Contribute
25+
26+
We welcome [issues](https://github.com/<org-name>/<repo-name>/issues) to and [pull requests](https://github.com/<org-name>/<repo-name>/pulls) against this repository!
27+
28+
To publish a new production version:
29+
* Create a PR to the `Alpha` branch with your changes. This will act as a "staging" branch.
30+
* When ready to publish a new production version, create a PR from `Alpha` to `master`. The Git Subject should include `[semver:patch|minor|release|skip]` to indicate the type of release.
31+
* On merge, the release will be published to the orb registry automatically.
32+
33+
For further questions/comments about this or other orbs, visit the Orb Category of [CircleCI Discuss](https://discuss.circleci.com/c/orbs).

‎_init/_CCIAddSecrets.sh‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
#!/bin/bash
2+
_CCIAddSecrets() {
3+
# Add CIRCLE_TOKEN env var to CircleCI
4+
echo
5+
echo "Adding CIRCLE_TOKEN env var to project on CircleCI"
6+
CCI_TOKEN_ENV_RESPONSE=$(curl -s -o /dev/null -w "%{http_code}" -X POST --header "Content-Type: application/json" -d "{\"name\":\"CIRCLE_TOKEN\", \"value\":\"$CCI_TOKEN\"}" "https://circleci.com/api/v1.1/project/github/${CCI_ORGANIZATION}/${CCI_REPO}/envvar?circle-token=${CCI_TOKEN}")
7+
if [ ! "$CCI_TOKEN_ENV_RESPONSE" == "201" ]
8+
then
9+
echo "Failed to add CIRCLE_TOKEN env var to CircleCI. Please try again later."
10+
exit 1
11+
else
12+
echo "...CIRCLE_TOKEN env var added to CircleCI"
13+
fi
14+
echo
15+
}

‎_init/_checkGithubAuth.sh‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
#!/bin/bash
2+
_checkGithubAuth() {
3+
GITAUTHCHECK=$(ssh -T [email protected] 2>&1)
4+
if [ -z $(echo "$GITAUTHCHECK" | grep -o "success") ]
5+
then
6+
printf "\e[1m\e[91mUnable to authenticate with GitHub\e[0m\n"
7+
echo "It doesn't appear you are authenticated with Github."
8+
echo "Ensure you have added your SSH keypair to enable pushing and pulling from this environment"
9+
echo "https://help.github.com/en/articles/adding-a-new-ssh-key-to-your-github-account"
10+
sleep 2
11+
exit 1
12+
else
13+
GITHUB_USER=$(echo "$GITAUTHCHECK" | cut -d " " -f 2 | tr -d "!")
14+
printf "\e[92mAuthenticated\e[0m\n"
15+
echo "Welcome $GITHUB_USER"
16+
echo
17+
fi
18+
}

0 commit comments

Comments
 (0)