You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
:page-description: Tutorial showing how to create an orb using the orb development kit.
12
+
:icons: font
13
+
:toc: macro
14
+
:toc-title:
15
+
16
+
This tutorial guides you through creating a new orb using the orb development kit. The starting point is creating a new repository on link:https://github.com[GitHub.com].
17
+
18
+
Following this tutorial you will:
19
+
20
+
* Create a GitHub repo for your orb.
21
+
* Add templated orb config, based on your requirements.
22
+
* Set up a CI/CD pipeline for orb development and put restrictions on who can contribute towards the development of your orb.
23
+
24
+
At the end of the tutorial you will be ready to configure your orb.
25
+
26
+
These steps are also outlined in the following video.
27
+
28
+
.Create and initialize an orb
29
+
video::5ta4RUwqOBI[youtube]
30
+
31
+
[#prerequisites]
32
+
== Prerequisites
33
+
34
+
* A GitHub account connected to your CircleCI account. See the link:/docs/first-steps/[Sign up and try] page for steps to get set up.
35
+
* link:/docs/local-cli/#installation[Set up the CircleCI CLI] on your local machine with a link:https://app.circleci.com/settings/user/tokens[personal access token]. Ensure you are using the latest version of the CircleCI CLI. You must be using version `v0.1.17087` or later.
36
+
+
37
+
```shell
38
+
$ circleci update
39
+
40
+
$ circleci version
41
+
```
42
+
* link:/docs/orb-author-intro/#register-a-namespace[Register a namespace] for your GitHub organization. Ensure the organization on GitHub is the owner for the CircleCI namespace for which you are developing your orb (this will be automatically configured correctly if you are using your own personal organization and namespace).
43
+
44
+
[#create-your-orb]
45
+
== Create your orb
46
+
47
+
[#create-a-new-repo]
48
+
=== 1. Create a new repo
49
+
50
+
Create a new, empty, link:https://github.com/new[GitHub repository]. The name of your repository is not critical, but something similar to "myProject-orb" is recommended.
51
+
52
+
NOTE: Ensure that the repository is completely empty. Uncheck any options such as "Add a README.md" or "Choose a license".
Once complete, you should see the generated git URL. Note it down, you will need it in step 4. You can select SSH or HTTPS, whichever you can authenticate with.
CAUTION: It is not necessary to pull down the orb repository. This will be completed when you run `orb init` in the next step. Pulling the repository before this will cause issues.
61
+
62
+
=== 2. Initialize your orb
63
+
64
+
Open a terminal and initialize your new orb project using the `orb init` CLI command as shown below. The `circleci orb init` command is called, followed by a path to create and initialize for your orb project. It is best practice to use the same name for this directory and the git project repo.
65
+
66
+
CAUTION: If you are using CircleCI server, you should ensure the `--private` flag is used here to keep your orbs private within your installation.
67
+
68
+
WARNING: Once an orb is initialized, it **cannot be switched from public to private or vice versa**. Please make sure to add the `--private` flag if you intend to create a private orb.
69
+
70
+
71
+
* To initialize a link:/docs/orb-intro/#public-orbs[public] orb:
72
+
+
73
+
```shell
74
+
circleci orb init </path/to/myProject-orb>
75
+
```
76
+
77
+
* To initialize a link:/docs/orb-intro/#private-orbs[private] orb:
=== 3. Choose the fully automated orb setup option
84
+
85
+
```shell
86
+
? Would you like to perform an automated setup of this orb?:
87
+
▸ Yes, walk me through the process.
88
+
No, I will handle everything myself.
89
+
```
90
+
91
+
When choosing the fully automated option, the link:https://github.com/CircleCI-Public/Orb-Template[orb template] is downloaded and automatically modified with your customized settings. The project will be followed on CircleCI with an automated CI/CD pipeline included.
92
+
93
+
For more information on the included CI/CD pipeline, see the link:/docs/creating-orbs/[Orb publishing process] page.
94
+
95
+
NOTE: If you would simply like a convenient way of downloading the link:https://github.com/CircleCI-Public/Orb-Template[orb template] you can opt to handle everything yourself. When choosing the manual option, see link:/docs/orb-author-validate-publish/[Manual orb authoring process] for instructions on how to author and publish your orb.
96
+
97
+
=== 4. Follow the prompts to set up your orb
98
+
99
+
In the background, the `orb init` command copies and customizes the link:https://github.com/CircleCI-Public/Orb-Template[orb template] based on your inputs. There are detailed `README.md` files within each directory that contain helpful information specific to the contents of each directory. You will also be asked for the remote git repository URL that you obtained back in step 1.
100
+
101
+
The link:https://github.com/CircleCI-Public/Orb-Template[orb template] contains a full CI/CD pipeline (described in link:/docs/creating-orbs/[orb publishing process]), which automatically link:/docs/orb-concepts/#orb-packing[packs], link:/docs/testing-orbs/[tests], and link:/docs/creating-orbs/[publishes] your orb.
102
+
103
+
In the setup process you will be asked if you would like to save your [Personal API Token]({{site.baseurl}}/managing-api-tokens/) into an `orb-publishing` [context]({{site.baseurl}}/contexts/). Saving this token is necessary for publishing development and production versions of your orb. If you have already made an orb in the past, you can skip this step, as the context will already exist.
104
+
105
+
=== 5. Restrict who can trigger jobs for the orb
106
+
107
+
Use link:/docs/contexts/#restrict-a-context-to-a-security-group-or-groups[security groups] to limit access to users that are allowed to trigger jobs. Only these users will have access to the private link:/docs/managing-api-tokens/[personal API token].
108
+
109
+
link:/docs/contexts/#restricting-a-context[Contexts] can be located by navigating to **Organization Settings > Contexts** in the web app. After creating your orb, you will have a new context called `orb-publishing`. Click into `orb-publishing` and add a **Security Group**.
110
+
111
+
.Secure contexts
112
+
video::ImPE969yv08[youtube]
113
+
114
+
=== 6. Push changes to Github
115
+
116
+
During the setup process, the `orb init` command prepares your automated orb development pipeline. The modified template code produced by the CLI must be pushed to the repository before the CLI can continue and automatically follow your project on CircleCI.
117
+
118
+
Run the following command from a separate terminal when prompted to do so, substituting the name of your default branch:
119
+
120
+
```shell
121
+
git push origin <default-branch>
122
+
```
123
+
124
+
Once complete, return to your terminal and confirm the changes have been pushed.
125
+
126
+
=== 7. Complete the setup
127
+
128
+
Once the changes have been pushed, return to your terminal and continue the setup process. The CLI will now automatically follow the project on CircleCI, and attempt to trigger a pipeline to build and test your orb with sample code.
129
+
130
+
You will be provided with a link to the project building on CircleCI where you can view the full pipeline. You should also see the CLI has automatically migrated you into a new development branch, named `alpha`. You can use any branch naming you would like, you do not need to exclusively develop on `alpha`.
131
+
132
+
=== 8. Enable Dynamic Configuration
133
+
134
+
Using the orb development kit makes use of link:/docs/dynamic-config/[Dynamic configuration], you will need to enable this feature. You will receive an error on your first pipeline that will state that this feature is not yet enabled.
135
+
136
+
Following the link:/docs/dynamic-config/#getting-started-with-dynamic-config-in-circleci[Getting started with dynamic config in CircleCI] guide, open the **Project Settings** page for your orb on CircleCI, navigate to the **Advanced** tab, and click on the **Enable dynamic config using setup workflows** button.
137
+
138
+
Once enabled, all future commits to your project will run through the full pipeline and test your orb. You could manually re-run the pipeline at this point, but since you are only working with sample code at this moment, it is not necessary.
139
+
140
+
=== 9. Develop your orb
141
+
142
+
From a non-default branch (you will be moved to the `alpha` branch automatically at setup), begin modifying the sample orb code to fit your requirements. On each _push_, your orb will be automatically built and tested. More information on developing your orb can be found on the link:/docs/orb-author/#writing-your-orb[Orb authoring process] page.
143
+
144
+
Be sure to view the link:https://github.com/CircleCI-Public/Orb-Template/blob/main/.circleci/test-deploy.yml[.circleci/test-deploy] file to view how your orb components are being tested, and modify your tests as you change your orb. Learn more about testing your orb on the link:/docs/testing-orbs/[Orb testing methodologies] page.
145
+
146
+
When you are ready to deploy the first production version of your orb, find information on deploying changes on the link:/docs/creating-orbs/[Orb publishing process] page.
Copy file name to clipboardExpand all lines: jekyll/_cci2/orb-author.md
+1-123Lines changed: 1 addition & 123 deletions
Original file line number
Diff line number
Diff line change
@@ -50,129 +50,7 @@ Follow the steps below to create, test and publish your own orb, using the orb d
50
50
### Getting started
51
51
{: #getting-started }
52
52
53
-
To begin creating your new orb with the orb development kit, follow the steps below. The starting point is creating a new repository on [GitHub.com](https://github.com).
54
-
55
-
Ensure the organization on GitHub is the owner for the [CircleCI namespace]({{site.baseurl}}/orb-concepts/#namespaces) for which you are developing your orb. You can also view the video below learn more on getting started. If this is your own personal organization and namespace, you need not worry.
56
-
57
-
<divclass="video-wrapper">
58
-
<iframewidth="560"height="315"src="https://www.youtube.com/embed/5ta4RUwqOBI"title="YouTube video player"frameborder="0"allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"allowfullscreen></iframe>
59
-
</div>
60
-
61
-
1.**Create a new _empty_[GitHub repository](https://github.com/new).**
62
-
63
-
The name of your repository is not critical, but we recommend something similar to "myProject-orb". 
64
-
65
-
**Note:** Ensure that the repository is completely empty. Uncheck any options such as "Add a README.md" or "Choose a license".
66
-
{: class="alert alert-warning"}
67
-
68
-
When complete, you will be brought to a page confirming your new repository and you should see the generated git URL. Note down the git URL, you will need it in step 4. You can select SSH or HTTPS, whichever you can authenticate with. 
69
-
70
-
**Note:** While you must create a local directory for your orb before initializing, it is not necessary to pull down the orb repository. This process will be completed in the `orb init` process and pulling the repository beforehand will cause issues.
71
-
{: class="alert alert-warning"}
72
-
73
-
1.**Update the CircleCI CLI**
74
-
75
-
Ensure you are using the latest version of the CircleCI CLI. You must be using version `v0.1.17087` of the CLI or later.
76
-
77
-
```shell
78
-
$ circleci update
79
-
80
-
$ circleci version
81
-
```
82
-
83
-
1. **Initialize your orb**
84
-
85
-
Open a terminal and initialize your new orb project using the `orb init` CLI command.
86
-
87
-
If you are using CircleCI server, you should ensure the `--private` flag is used here to keep your orbs private within your installation.
88
-
89
-
To initialize a **[public]({{site.baseurl}}/orb-intro/#public-orbs)** orb:
90
-
91
-
```shell
92
-
circleci orb init /path/to/myProject-orb
93
-
```
94
-
To initialize a **[private]({{site.baseurl}}/orb-intro/#private-orbs)** orb:
Once an orb is initialized, it **cannot be switched from public to private or vice versa**. Please make sure to add the `--private` flag if you intend to create a private orb.
100
-
{: class="alert alert-warning"}
101
-
102
-
The `circleci orb init`command is called, followed by a path that will be created and initialized for our orb project. It is best practice to use the same name for this directory and the git project repo.
103
-
104
-
105
-
1. **Choose the fully automated orb setup option.**
106
-
107
-
```shell
108
-
? Would you like to perform an automated setup of this orb?:
109
-
▸ Yes, walk me through the process.
110
-
No, I'll handle everything myself.
111
-
```
112
-
113
-
When choosing the manual option, see [Manual Orb Authoring Process]({{site.baseurl}}/orb-author-validate-publish/) for instructions on how to publish your orb.
114
-
115
-
When choosing the fully automated option, the [Orb-Template](https://github.com/CircleCI-Public/Orb-Template) will be downloaded and automatically modified with your customized settings. The project will be followed on CircleCI with an automated CI/CD pipeline included.
116
-
117
-
For more information on the included CI/CD pipeline, see the [Orb Publishing Process]({{site.baseurl}}/creating-orbs/) documentation.
118
-
119
-
Alternatively, if you would simply like a convenient way of downloading the [Orb-Template](https://github.com/CircleCI-Public/Orb-Template) you can opt to handle everything yourself.
120
-
121
-
1. **Follow the prompts to configure and set up your orb.**
122
-
123
-
In the background, the `orb init` command will be copying and customizing the [Orb Template](https://github.com/CircleCI-Public/Orb-Template) based on your inputs. There are detailed `README.md` files within each directory that contain helpful information specific to the contents of each directory. You will also be asked for the remote git repository URL that you obtained back in step 1.
124
-
125
-
The [Orb Template](https://github.com/CircleCI-Public/Orb-Template) contains a full CI/CD pipeline (described in [Orb Publishing Process]({{site.baseurl}}/creating-orbs/)) which automatically [packs]({{site.baseurl}}/orb-concepts/#orb-packing), [tests]({{site.baseurl}}/testing-orbs/), and [publishes](https://circleci.com/docs/creating-orbs/) your orb.
126
-
127
-
In the setup process you will be asked if you would like to save your [Personal API Token]({{site.baseurl}}/managing-api-tokens/) into an `orb-publishing` [context]({{site.baseurl}}/contexts/). Saving this token is necessary for publishing development and production versions of your orb. If you have already made an orb in the past, you can skip this step, as the context will already exist.
128
-
129
-
1. **Ensure the context is restricted**
130
-
131
-
Restrict a context by navigating to _Organization Settings > Contexts_.
132
-
133
-
After completing your orb, you should see a new context called `orb-publishing`. Click into `orb-publishing` and add a _Security Group_. Use Security Groups to limit access to users that are allowed to trigger jobs. Only these users will have access to the private [Personal API Token]({{site.baseurl}}/managing-api-tokens/).
134
-
135
-
For more information, see the [Contexts]({{site.baseurl}}/contexts/#restricting-a-context) guide.
During the setup process, the `orb init` command takes steps to prepare your automated orb development pipeline. The modified template code produced by the CLI must be pushed to the repository before the CLI can continue and automatically follow your project on circleci.com. Run the following command from a separate terminal when prompted to do so, substituting the name of your default branch:
145
-
```shell
146
-
git push origin <default-branch>
147
-
```
148
-
Once complete, return to your terminal and confirm the changes have been pushed.
149
-
150
-
1. **Complete the setup**
151
-
152
-
Once the changes have been pushed, return to your terminal and continue the setup process. The CLI will now automatically follow the project on CircleCI, and attempt to trigger a pipeline to build and test your orb with sample code.
153
-
154
-
You will be provided with a link to the project building on CircleCI where you can view the full pipeline.
155
-
You should also see the CLI has automatically migrated you into a new development branch, named `alpha`. You can use any branch naming you would like, you do not need to exclusively develop on `alpha`.
156
-
157
-
1. **Enable Dynamic Configuration**
158
-
159
-
Because we are making use of [dynamic configuration]({{site.baseurl}}/dynamic-config/), we must first enable this feature. You will receive an error on your first pipeline that will state that this feature is not yet enabled.
160
-
161
-
Following the [Getting started with dynamic config in CircleCI]({{site.baseurl}}/dynamic-config/#getting-started-with-dynamic-config-in-circleci), open the **Project Settings** page for your orb on CircleCI, navigate to the **Advanced** tab, and click on the **Enable dynamic config using setup workflows** button.
162
-
163
-
Once enabled, all future commits to your project will run through the full pipeline and test your orb. We could manually re-run the pipeline at this point, but since we are only working with sample code at this moment, we don't need to.
164
-
165
-
1. **Develop your orb**
166
-
167
-
From a non-default branch (you will be moved to the `alpha` branch automatically at setup), begin modifying the sample orb code to your liking. On each _push_, your orb will be automatically built and tested.
168
-
169
-
Be sure to view the _[.circleci/test-deploy](https://github.com/CircleCI-Public/Orb-Template/blob/main/.circleci/test-deploy.yml)_ file to view how your orb components are being tested, and modify your tests as you change your orb. Learn more about testing your orb in the [Orb Testing documentation]({{site.baseurl}}/testing-orbs/).
170
-
171
-
When you are ready to deploy the first production version of your orb, find information on deploying changes in the [Orb Publishing Process]({{site.baseurl}}/creating-orbs/) guide.
0 commit comments